@exodus/stasis-plugins 1.0.0-beta.2 → 1.0.0-beta.3

package/src/plugins.js

@@ -1,9 +1,5 @@
-// Plugin <-> preload coordination (resolvePluginState): decides which State a bundler
-// plugin drives, given its options and the ambient preload. The per-file classification
-// helpers (pathExt / parseResourcesOption / classifyExtension) live in util.js -- they're
-// pure and shared with State's `--fs` capture, so both paths classify against one source
-// of truth. Kept out of state.js because the coordination only consults State.preload +
-// Config helpers, never State internals.
+// Plugin <-> preload coordination (resolvePluginState): decides which State a bundler plugin
+// drives, given its options and the ambient preload.
 
 import assert from 'node:assert/strict'
 
@@ -12,58 +8,42 @@ import { ensureStateForLoader, isLoaderInstalled } from '@exodus/stasis-core/hoo
 import { State } from '@exodus/stasis-core/state'
 import { extSetsEqual, parseResourcesOption } from '@exodus/stasis-core/util'
 
-// Decides which State a bundler plugin (StasisWebpack / StasisEsbuild) should run against,
-// given its constructor options and the ambient preload (or lack thereof). Returns either
-// { state: null, isNoop: true } -- plugin should register no hooks and become inert -- or
-// { state, isNoop: false } -- plugin should drive the returned State.
-//
-// The lockfile is always unified: a plugin never specifies its own lockfile position
-// (validatePluginOptions rejects `lockFile`). When an ambient preload exists the plugin
-// MUST share it -- it either reuses the preload State outright or runs as a sidecar that
-// shares the preload's hashes/entries/modules + lockfile data. Only the BUNDLE may split
-// off per-plugin (via bundleFile, a sidecar). A process that genuinely needs a non-default
-// lockfile location sets it process-wide (Config / EXODUS_STASIS_LOCK_FILE), not per-plugin.
-//
-// Rules:
-//  1. Plugin asking for any lockfile mode other than 'none' / 'ignore' requires a preload.
-//     Without one it's a hard throw -- the lockfile would otherwise only cover the bundled
-//     app and silently miss every dependency the bundler itself pulled in.
-//  2. With a preload, the plugin's lock mode must agree with the preload's.
-//  3. Lockfile is unified: when plugin and preload align we reuse the preload State so a
-//     single lockfile is written.
-//  4. Bundle may split: with a preload that already has bundle on, the plugin cannot disable
-//     bundle and the bundle mode must match. The plugin's bundleFile, however, may differ
-//     -- in which case we construct a sidecar State sharing the preload's lockfile data.
+// Decides which State a bundler plugin runs against, given its options and the ambient preload.
+// Returns { state: null, isNoop: true } (inert -- register no hooks) or { state, isNoop: false }.
+// The lockfile is always unified (plugins can't set lockFile); only the BUNDLE may split per-plugin
+// (bundleFile -> sidecar). Rules, referenced by number in the code below:
+//  0. No preload, not under `stasis run`, no lock/bundle option -> inert (safe on a plain build).
+//  1. A writing/verifying lock mode without a preload throws (it would miss the bundler's own deps).
+//  2. With a preload, the plugin's lock mode must agree with it.
+//  3. When plugin and preload align, reuse the preload State (single lockfile).
+//  4. Preload with bundle on: plugin can't disable it and the mode must match; bundleFile may differ.
 //  5. Same bundleFile (or unspecified) reuses the preload State.
-//  6. Different bundleFile creates a sidecar.
-//  7. Plugin with lock='none' AND bundle='none' and no preload is a no-op (lets framework
-//     plugins be env-controlled off without throwing on the lock=none/bundle=none invariant).
+//  6. Different bundleFile creates a sidecar sharing the preload's lockfile data.
+//  7. lock='none' AND bundle='none' with no preload is a no-op (env-controlled-off framework plugins).
 export function resolvePluginState(label, options, cwd) {
   validatePluginOptions(label, options)
-  const { scope, lock, bundle, bundleFile, resourcesBundleFile, debug, childProcess, resources } = options
-  // Same-instance fast path: the plugin's stasis-core IS the binary's, the
-  // hooks are installed, but the lazy initState hasn't fired yet (plugin
-  // ran AHEAD of the first user-file load -- webpack constructs plugins
-  // during config-parse before user code executes). Force-init now so the
-  // plugin lands in the ambient branch and inherits the loader's Config.
-  // We deliberately do NOT do this when the loader is a SEPARATE module
-  // instance (different stasis-core copy in the plugin's node_modules vs
-  // the binary's): force-init there would create a phantom State.preload
-  // with its own beforeExit/exit save handlers that race the real loader's
-  // lockfile write. Cross-instance detection lives below via env vars.
+  const { scope, lock, bundle, bundleFile, resourcesBundleFile, debug, childProcess, packageJSON, resources } = options
+  // Same-instance fast path: loader installed but lazy initState hasn't fired (webpack builds plugins
+  // before user code). Force-init so the plugin lands in the ambient branch. NOT for a separate
+  // stasis-core copy -- that would mint a phantom State.preload racing the real loader's write.
   if (!State.preload && isLoaderInstalled()) ensureStateForLoader()
   const ambient = State.preload
 
   if (!ambient) {
+    // "Under stasis run" detection: the bin script always exports EXODUS_STASIS_LOCK, so it's a
+    // process-wide signal regardless of which stasis-core copy hosts this code.
+    const underStasisRun = process.env.EXODUS_STASIS_LOCK !== undefined
+
+    // Rule 0: no preload, not under `stasis run`, no lock/bundle option -> do nothing, so a bare
+    // plugin sits inertly in a plain build. Capture is governed elsewhere (env or explicit options).
+    if (!underStasisRun && lock === undefined && bundle === undefined) {
+      return { state: null, isNoop: true }
+    }
+
     if (lock === 'none' && bundle === 'none') return { state: null, isNoop: true } // Rule 7
-    // Rule 7 needs BOTH to be 'none'. A partial opt-out -- one field is 'none' but
-    // the other was simply omitted -- would otherwise fall through to either a
-    // misleading Rule 1 throw about the default lockfile mode, or to Config's
-    // generic "stasis needs a lockfile or a bundle" RangeError. Catch the partial
-    // case explicitly. Only fires when the OTHER field is undefined: an active
-    // bundle mode like `bundle:'load'` / `'frozen'` / `'add'` paired with
-    // `lock:'none'` is a legitimate "bundle as trust root" config that Config
-    // accepts (see config.js's bundle=load / bundle=frozen rules).
+    // A partial opt-out (one field 'none', the other omitted) would otherwise hit a misleading
+    // Rule 1 throw or Config's generic error; catch it explicitly. An active bundle mode paired
+    // with lock='none' is a legitimate "bundle as trust root" config, so only fire when the other is undefined.
     if ((lock === 'none' && bundle === undefined) || (bundle === 'none' && lock === undefined)) {
       throw new Error(
         `${label}: to opt out of stasis without a preload, pass BOTH lock='none' and bundle='none' ` +
@@ -71,18 +51,9 @@ export function resolvePluginState(label, options, cwd) {
         `bundle=${bundle === undefined ? 'default' : `'${bundle}'`})`
       )
     }
-    // Cross-instance "running under stasis run" detection: `stasis run`'s
-    // bin script always sets EXODUS_STASIS_LOCK on the spawned child (even
-    // for the default `--lock=add`), so the env var is a reliable
-    // process-wide signal regardless of which stasis-core copy is hosting
-    // this code. When set, the runtime's loader is providing full lockfile
-    // coverage for the process; the plugin's lockfile (at its own path,
-    // typically a sidecar like `sources.stasis.lock.json`) is a sibling
-    // artifact covering bundler-side resolutions, and the "lock=add needs
-    // a preload" rationale doesn't apply. Skip that rule under stasis run;
-    // Config below will pick up env-var defaults (lock/scope/bundle) for
-    // the standalone plugin State.
-    const underStasisRun = process.env.EXODUS_STASIS_LOCK !== undefined
+    // A writing/verifying lock (add|replace|frozen) still needs a preload unless under stasis run
+    // (whose loader gives full coverage). `lock` may be undefined here if only a writing `bundle`
+    // was passed, so the throw below distinguishes a defaulted mode from an explicit one.
     const effectiveLock = lock ?? DEFAULT_LOCK
     if (!underStasisRun && effectiveLock !== 'none' && effectiveLock !== 'ignore') {
       const phrasing = lock === undefined
@@ -96,16 +67,12 @@ export function resolvePluginState(label, options, cwd) {
     return { state: new State(cwd, options), isNoop: false }
   }
 
-  // Preload is active. Since `lockFile` is not a plugin option, the lockfile is
-  // necessarily the ambient's -- the plugin shares it (reuse or sidecar below).
-  // Enforce coordination on the remaining fields before deciding which.
+  // Preload active: the lockfile is necessarily the ambient's. Enforce field coordination, then reuse or sidecar.
   const pc = ambient.config
   if (lock !== undefined && lock !== pc.lock) {
     throw new Error(`${label}: lock='${lock}' conflicts with active preload lock='${pc.lock}'`)
   }
-  // scope/debug/childProcess must agree with the preload on every preload-coupled path -- reuse
-  // adopts preload's config wholesale, and sidecar copies it field by field. Catch a
-  // disagreement here rather than silently overriding the user's value.
+  // scope/debug/childProcess must agree with the preload (reuse adopts it, sidecar copies it).
   if (scope !== undefined && scope !== pc.scope) {
     throw new Error(`${label}: scope='${scope}' conflicts with active preload scope='${pc.scope}'`)
   }
@@ -115,10 +82,11 @@ export function resolvePluginState(label, options, cwd) {
   if (childProcess !== undefined && childProcess !== pc.childProcess) {
     throw new Error(`${label}: childProcess=${childProcess} conflicts with active preload childProcess=${pc.childProcess}`)
   }
-  // resources is process-wide (a Config field), so a plugin's allowlist must agree with
-  // the preload's -- reuse adopts it wholesale, a sidecar inherits it. Compare the parsed
-  // sets (order/dupes/case don't matter), failing on a real disagreement rather than
-  // letting one plugin silently widen the attested asset set.
+  if (packageJSON !== undefined && packageJSON !== pc.packageJSON) {
+    throw new Error(`${label}: packageJSON=${packageJSON} conflicts with active preload packageJSON=${pc.packageJSON}`)
+  }
+  // resources is process-wide, so a plugin's allowlist must agree with the preload's -- compare
+  // parsed sets (order/dupes/case-insensitive) to prevent one plugin silently widening the asset set.
   if (resources !== undefined) {
     const parsed = parseResourcesOption(label, resources)
     if (!extSetsEqual(parsed, pc.resources)) {
@@ -128,10 +96,8 @@ export function resolvePluginState(label, options, cwd) {
     }
   }
 
-  // A plugin instance is attaching to the preload now (its constructor called us). Mark it so the
-  // preload's bundle `reason` map can tell apart files run merely fs-READS during the build (the
-  // plugin's modules, e.g. webpack+babel reading app source through --fs) from genuine run
-  // dependencies recorded before any plugin existed. See State#bundleReason.
+  // Mark the plugin attached so the preload's bundle `reason` map can distinguish files merely
+  // fs-READ during the build from genuine run dependencies recorded before any plugin existed.
   ambient.markPluginAttached()
 
   if (pc.bundle) {
@@ -151,8 +117,7 @@ export function resolvePluginState(label, options, cwd) {
       assertOptionsMatchConfig(pc, options)
       return { state: ambient, isNoop: false }
     }
-    // Rule 6: different path -- sidecar inherits preload's modes, overrides bundleFile
-    // (and resourcesBundleFile if the plugin provided one for a split layout).
+    // Rule 6: different path -- sidecar inherits preload's modes, overrides bundleFile.
     const sidecar = new State(cwd, {
       parent: ambient,
       scope: pc.scope,
@@ -162,8 +127,9 @@ export function resolvePluginState(label, options, cwd) {
       resourcesBundleFile,
       debug: pc.debug,
       childProcess: pc.childProcess,
+      packageJSON: pc.packageJSON,
       resources: [...pc.resources],
-      // carried over: sidecars skip stasis.config.json discovery, which may have set it
+      // carried over: sidecars skip stasis.config.json discovery
       brotliQuality: pc.brotliQuality,
     })
     return { state: sidecar, isNoop: false }
@@ -171,14 +137,9 @@ export function resolvePluginState(label, options, cwd) {
 
   // Preload exists but has no bundle.
   if (bundle === undefined || bundle === 'none' || bundle === 'ignore') {
-    // Plugin doesn't want a bundle either: just reuse preload for lockfile coverage.
-    // bundle='ignore' here legitimately disagrees with preload's bundleMode ('none'),
-    // both mean "no bundle written by the plugin", so skip the bundle field in the
-    // cross-check rather than letting assertOptionsMatchConfig flag the difference.
-    // Defense-in-depth: the strip is only safe when the preload's bundleMode is
-    // actually in the no-bundle equivalence class. If a future bundleMode reads as
-    // `!pc.bundle` but means something else, the strip would silently mask a real
-    // disagreement -- the assert pins the contract to today's two values.
+    // Plugin wants no bundle either: reuse preload for lockfile coverage. bundle='ignore' vs the
+    // preload's 'none' both mean "no plugin bundle", so strip the bundle field from the cross-check;
+    // the assert pins that strip to today's no-bundle values so a future mode can't silently mask a disagreement.
     assert.ok(pc.bundleMode === 'none' || pc.bundleMode === 'ignore',
       `unexpected preload bundleMode='${pc.bundleMode}' in the no-bundle branch`)
     const { bundle: _b, ...rest } = options
@@ -200,6 +161,7 @@ export function resolvePluginState(label, options, cwd) {
     resourcesBundleFile,
     debug: pc.debug,
     childProcess: pc.childProcess,
+    packageJSON: pc.packageJSON,
     resources: [...pc.resources],
     brotliQuality: pc.brotliQuality, // carried over, like the Rule 6 sidecar above
   })