@exodus/stasis-core 1.0.0-beta.1 → 1.0.0-beta.10

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/src/config.js CHANGED
@@ -1,303 +1,222 @@
1
1
  import assert from 'node:assert/strict'
2
2
 
3
+ import { diskHost } from './host.js'
3
4
  import { canonicalizePath } from './state-util.js'
4
- import { extSetsEqual, parseResourcesOption } from './util.js'
5
+ import { extSetsEqual, isBrotliQuality, parseBrotliQuality, parseResourcesOption } from './util.js'
5
6
 
6
- const VALID_SCOPE = new Set(['node_modules', 'full'])
7
- const VALID_LOCK = new Set(['none', 'ignore', 'add', 'replace', 'frozen'])
8
- const VALID_BUNDLE = new Set(['none', 'ignore', 'add', 'replace', 'load', 'frozen'])
9
- const VALID_FS = new Set(['sync', 'async'])
10
-
11
- // The defaults Config applies when neither env nor options specify a value.
12
- // Exported so callers (plugins.js error messages) can reference the same source of
13
- // truth instead of hardcoding the literal -- a default drift then surfaces at one
14
- // place, not silently in a user-facing message.
15
7
  export const DEFAULT_LOCK = 'add'
16
8
  export const DEFAULT_BUNDLE = 'none'
17
9
  export const DEFAULT_SCOPE = 'full'
18
10
 
19
- // Strict boolean env parsing: ''/'0'/'false' -> false, '1'/'true' -> true. Anything else
20
- // ('no', 'off', ...) throws -- a truthiness parse would read those as *enabling* the
21
- // toggle, and a misconfigured env var should fail loudly, not silently flip a feature on.
11
+ // Strict, not truthy: a truthiness parse would read 'no'/'off' as *enabling* the toggle.
22
12
  const envBool = (name, value) => {
23
13
  if (value === '' || value === '0' || value === 'false') return false
24
14
  if (value === '1' || value === 'true') return true
25
15
  throw new RangeError(`${name} must be ''/'0'/'false' or '1'/'true' (got '${value}')`)
26
16
  }
27
17
 
28
- // EXODUS_STASIS_RESOURCES is a comma-separated extension list; split + trim + drop
29
- // empties so '' and ' png , svg ' normalize predictably (parseResourcesOption then
30
- // validates each entry). An empty/unset env var means "no allowlist".
18
+ // EXODUS_STASIS_RESOURCES is a comma-separated extension list; empty/unset means "no allowlist".
31
19
  const envList = (value) => value.split(',').map((s) => s.trim()).filter(Boolean)
32
20
 
33
- const OPTION_KEYS = ['scope', 'lock', 'bundle', 'bundleFile', 'resourcesBundleFile', 'debug', 'resources', 'childProcess']
21
+ // Every option: its env var, how the env string parses (strings pass through) and, for a non-string
22
+ // option, how a `new Config()` option does. `lockFile` is flag/env-only (never from stasis.config.json).
23
+ const OPTIONS = {
24
+ scope: { env: 'EXODUS_STASIS_SCOPE', valid: new Set(['node_modules', 'full']) },
25
+ lock: { env: 'EXODUS_STASIS_LOCK', valid: new Set(['none', 'ignore', 'add', 'replace', 'frozen']) },
26
+ lockFile: { env: 'EXODUS_STASIS_LOCK_FILE', type: 'string' },
27
+ bundle: { env: 'EXODUS_STASIS_BUNDLE', valid: new Set(['none', 'ignore', 'add', 'replace', 'load', 'frozen']) },
28
+ bundleFile: { env: 'EXODUS_STASIS_BUNDLE_FILE', type: 'string' },
29
+ resourcesBundleFile: { env: 'EXODUS_STASIS_RESOURCES_BUNDLE_FILE', type: 'string' },
30
+ debug: { env: 'EXODUS_STASIS_DEBUG', parse: envBool, type: 'boolean' },
31
+ childProcess: { env: 'EXODUS_STASIS_CHILD_PROCESS', parse: envBool, type: 'boolean' },
32
+ packageJSON: { env: 'EXODUS_STASIS_PACKAGE_JSON', parse: envBool, type: 'boolean' },
33
+ fs: { env: 'EXODUS_STASIS_FS', valid: new Set(['sync', 'async']) },
34
+ brotliQuality: { env: 'EXODUS_STASIS_BROTLI_QUALITY', parse: parseBrotliQuality },
35
+ // Compared as parsed sets, not raw strings: ['png','svg'] and 'svg,png' are the same allowlist.
36
+ resources: { env: 'EXODUS_STASIS_RESOURCES', parse: (name, value) => parseResourcesOption('env', envList(value)), option: (value) => parseResourcesOption('options', value) },
37
+ }
38
+ const OPTION_KEYS = Object.keys(OPTIONS)
39
+ const CONFIG_FILE_KEYS = OPTION_KEYS.filter((key) => key !== 'lockFile')
40
+ const PLUGIN_OPTION_KEYS = ['scope', 'lock', 'bundle', 'bundleFile', 'resourcesBundleFile', 'debug', 'childProcess', 'packageJSON', 'resources']
41
+
42
+ const assertKnownKeys = (keys, known, what) => {
43
+ const unknown = keys.filter((key) => !known.includes(key))
44
+ assert.equal(unknown.length, 0, `Unknown ${what} options: ${unknown.join(', ')}`)
45
+ }
46
+
47
+ // One option's membership/type rule; the cross-option rules live in #checkInvariants.
48
+ function assertOption(key, value) {
49
+ const { valid, type } = OPTIONS[key]
50
+ if (valid) assert.ok(valid.has(value), `Invalid ${key}: ${value}`)
51
+ else if (type) assert.equal(typeof value, type, `${key} must be a ${type}`)
52
+ }
53
+
54
+ // Equal for the option's type: `resources` is a Set.
55
+ const assertSame = (key, actual, expected, message) => {
56
+ if (key === 'resources') assert.ok(extSetsEqual(actual, expected), message)
57
+ else assert.equal(actual, expected)
58
+ }
34
59
 
35
- // Plugins accept the same options as Config but want to validate without constructing one,
36
- // since constructing State has side effects. Mirror Config's per-field validation.
60
+ // Plugins validate the same options without constructing a Config (which has side effects).
37
61
  export function validatePluginOptions(label, options) {
38
- const rest = { ...options }
39
- for (const key of OPTION_KEYS) delete rest[key]
40
- assert.equal(Object.keys(rest).length, 0, `Unknown ${label} options: ${Object.keys(rest).join(', ')}`)
41
- const { scope, lock, bundle, bundleFile, resourcesBundleFile, debug, resources, childProcess } = options
42
- if (scope !== undefined) assert.ok(VALID_SCOPE.has(scope), `Invalid scope: ${scope}`)
43
- if (lock !== undefined) assert.ok(VALID_LOCK.has(lock), `Invalid lock: ${lock}`)
44
- if (bundle !== undefined) assert.ok(VALID_BUNDLE.has(bundle), `Invalid bundle: ${bundle}`)
45
- if (bundleFile !== undefined) assert.equal(typeof bundleFile, 'string', 'bundleFile must be a string')
46
- if (resourcesBundleFile !== undefined) assert.equal(typeof resourcesBundleFile, 'string', 'resourcesBundleFile must be a string')
47
- if (debug !== undefined) assert.equal(typeof debug, 'boolean', 'debug must be a boolean')
48
- if (childProcess !== undefined) assert.equal(typeof childProcess, 'boolean', 'childProcess must be a boolean')
49
- // parseResourcesOption is the validator: it throws on a non-array, non-string entries,
50
- // malformed extensions, or a code extension (those are always tracked, never resources).
51
- if (resources !== undefined) parseResourcesOption(label, resources)
62
+ assertKnownKeys(Object.keys(options), PLUGIN_OPTION_KEYS, label)
63
+ for (const key of PLUGIN_OPTION_KEYS) {
64
+ if (options[key] === undefined) continue
65
+ if (key === 'resources') parseResourcesOption(label, options.resources)
66
+ else assertOption(key, options[key])
67
+ }
52
68
  }
53
69
 
54
- // When a plugin runs against a State that already exists (preload path), the active Config
55
- // is authoritative. Any options the plugin was given must agree with it.
70
+ // The active Config is authoritative; options a plugin was given must agree with it.
56
71
  export function assertOptionsMatchConfig(config, options) {
57
- const { scope, lock, bundle, bundleFile, resourcesBundleFile, debug, childProcess } = options
58
- // `resources` is intentionally NOT cross-checked here: it's a Set (needs set-equality,
59
- // which assert.equal can't express) and is coordinated explicitly in resolvePluginState
60
- // before this runs -- don't "fix" the omission with assert.equal(config.resources, ...).
61
72
  try {
62
- if (scope !== undefined) assert.equal(config.scope, scope)
63
- if (lock !== undefined) assert.equal(config.lock, lock)
64
- if (bundle !== undefined) assert.equal(config.bundleMode, bundle)
65
- if (bundleFile !== undefined) assert.equal(config.bundleFile, bundleFile)
66
- if (resourcesBundleFile !== undefined) assert.equal(config.resourcesBundleFile, resourcesBundleFile)
67
- if (debug !== undefined) assert.equal(config.debug, debug)
68
- if (childProcess !== undefined) assert.equal(config.childProcess, childProcess)
73
+ // `resources` is deliberately NOT checked here: it's a Set, coordinated in resolvePluginState.
74
+ for (const key of PLUGIN_OPTION_KEYS) {
75
+ if (key !== 'resources' && options[key] !== undefined) assert.equal(config[key === 'bundle' ? 'bundleMode' : key], options[key])
76
+ }
69
77
  } catch (cause) {
70
- // Re-throw with the underlying assertion message folded into the top-level
71
- // text -- a plugin author hitting this gets the offending field's name and
72
- // expected/actual values without having to inspect err.cause.
73
78
  throw new Error(`Plugin options conflict with active stasis state: ${cause.message}`, { cause })
74
79
  }
75
80
  }
76
81
 
77
82
  export class Config {
78
83
  #env
84
+ #host
79
85
  #explicit
80
- #scope
81
- #lock
82
- #lockFile
83
- #bundle
84
- #bundleFile
85
- #resourcesBundleFile
86
- #resources
87
- #debug
88
- #childProcess
89
- #fs
90
-
91
- // Options match the CLI flags (scope/lock/lockFile/bundle/bundleFile/resourcesBundleFile/debug/
92
- // resources/childProcess/fs).
93
- // Env vars take effect at construction time; if both env and an option are set they must
94
- // agree. Likewise, any explicit constructor option is treated as authoritative: a later
95
- // `loadConfig` call (which reads stasis.config.json) must agree with it -- the alternative
96
- // (silently overwriting `--scope=full` with the file's `"scope":"node_modules"`)
97
- // was a footgun the CLI couldn't detect, since the flag was happily accepted
98
- // and then quietly ignored.
86
+ #opts
87
+ #shardSignalFlush
88
+
89
+ // Env and options must agree when both are set; #explicit is kept so a later loadConfig can't override them.
99
90
  constructor(options = {}) {
100
- const { scope, lock, lockFile, bundle, bundleFile, resourcesBundleFile, debug, resources, childProcess, fs, ...rest } = options
101
- assert.equal(Object.keys(rest).length, 0, `Unknown Config options: ${Object.keys(rest).join(', ')}`)
102
- this.#explicit = { scope, lock, lockFile, bundle, bundleFile, resourcesBundleFile, debug, resources, childProcess, fs }
103
-
104
- this.#env = {
105
- scope: process.env.EXODUS_STASIS_SCOPE || undefined,
106
- lock: process.env.EXODUS_STASIS_LOCK || undefined,
107
- lockFile: process.env.EXODUS_STASIS_LOCK_FILE || undefined,
108
- bundle: process.env.EXODUS_STASIS_BUNDLE || undefined,
109
- bundleFile: process.env.EXODUS_STASIS_BUNDLE_FILE || undefined,
110
- resourcesBundleFile: process.env.EXODUS_STASIS_RESOURCES_BUNDLE_FILE || undefined,
111
- debug: process.env.EXODUS_STASIS_DEBUG || undefined,
112
- resources: process.env.EXODUS_STASIS_RESOURCES || undefined,
113
- childProcess: process.env.EXODUS_STASIS_CHILD_PROCESS || undefined,
114
- fs: process.env.EXODUS_STASIS_FS || undefined,
115
- }
91
+ const { env = process.env, host = diskHost, ...rest } = options
92
+ assertKnownKeys(Object.keys(rest), OPTION_KEYS, 'Config')
93
+ // An empty-string path/mode option is unset, as its resolution below treats it; #explicit must
94
+ // agree, or loadConfig would refuse a stasis.config.json for not matching a phantom override.
95
+ const explicit = Object.fromEntries(Object.entries(rest).map(([key, value]) =>
96
+ [key, value === '' && (OPTIONS[key].valid || OPTIONS[key].type === 'string') ? undefined : value]))
97
+ this.#host = host
98
+ this.#explicit = explicit
99
+ // An env var set to '' counts as unset.
100
+ this.#env = Object.fromEntries(OPTION_KEYS.map((key) => [key, env[OPTIONS[key].env] || undefined]))
116
101
 
117
102
  try {
118
- if (this.#env.scope !== undefined && scope !== undefined) assert.equal(this.#env.scope, scope)
119
- if (this.#env.lock !== undefined && lock !== undefined) assert.equal(this.#env.lock, lock)
120
- if (this.#env.lockFile !== undefined && lockFile !== undefined) {
121
- assert.equal(this.#env.lockFile, lockFile)
122
- }
123
- if (this.#env.bundle !== undefined && bundle !== undefined) assert.equal(this.#env.bundle, bundle)
124
- if (this.#env.bundleFile !== undefined && bundleFile !== undefined) {
125
- assert.equal(this.#env.bundleFile, bundleFile)
126
- }
127
- if (this.#env.resourcesBundleFile !== undefined && resourcesBundleFile !== undefined) {
128
- assert.equal(this.#env.resourcesBundleFile, resourcesBundleFile)
129
- }
130
- if (this.#env.debug !== undefined && debug !== undefined) {
131
- assert.equal(envBool('EXODUS_STASIS_DEBUG', this.#env.debug), debug)
132
- }
133
- if (this.#env.childProcess !== undefined && childProcess !== undefined) {
134
- assert.equal(envBool('EXODUS_STASIS_CHILD_PROCESS', this.#env.childProcess), childProcess)
135
- }
136
- if (this.#env.fs !== undefined && fs !== undefined) assert.equal(this.#env.fs, fs)
137
- // Compare parsed sets, not the raw strings: ['png','svg'] and 'svg,png' are the
138
- // same allowlist. An empty/unset env var is "no env opinion" (handled by `||
139
- // undefined` above), so this only fires on two genuinely different non-empty lists.
140
- if (this.#env.resources !== undefined && resources !== undefined) {
141
- assert.ok(
142
- extSetsEqual(parseResourcesOption('env', envList(this.#env.resources)), parseResourcesOption('options', resources)),
143
- 'resources option does not match EXODUS_STASIS_RESOURCES'
144
- )
103
+ for (const key of OPTION_KEYS) {
104
+ if (this.#env[key] !== undefined && explicit[key] !== undefined) {
105
+ assertSame(key, this.#envValue(key), this.#explicitValue(key), 'resources option does not match EXODUS_STASIS_RESOURCES')
106
+ }
145
107
  }
146
108
  } catch (cause) {
147
109
  throw new Error('Config options can not override stasis env', { cause })
148
110
  }
149
111
 
150
- this.#scope = this.#env.scope || scope || DEFAULT_SCOPE
151
- this.#lock = this.#env.lock || lock || DEFAULT_LOCK
152
- this.#lockFile = this.#env.lockFile || lockFile || undefined
153
- this.#bundle = this.#env.bundle || bundle || DEFAULT_BUNDLE
154
- this.#bundleFile = this.#env.bundleFile || bundleFile || undefined
155
- this.#resourcesBundleFile = this.#env.resourcesBundleFile || resourcesBundleFile || undefined
156
- this.#debug = this.#env.debug !== undefined ? envBool('EXODUS_STASIS_DEBUG', this.#env.debug) : (debug ?? false)
157
- this.#childProcess = this.#env.childProcess !== undefined ? envBool('EXODUS_STASIS_CHILD_PROCESS', this.#env.childProcess) : (childProcess ?? false)
158
- // env wins over the option, like scope/lock/bundle; undefined means "fs untouched" (off).
159
- this.#fs = this.#env.fs || fs || undefined
160
- // env wins over the option (it's the process-wide signal); parseResourcesOption
161
- // normalizes both to a Set of lowercase extensions/filenames, or empty when neither set.
162
- this.#resources = parseResourcesOption(
163
- 'resources',
164
- this.#env.resources !== undefined ? envList(this.#env.resources) : resources
165
- )
112
+ // Strings: env, else the option, else the default ('' falls through); booleans keep a false.
113
+ const str = (key, fallback) => this.#envValue(key) || explicit[key] || fallback
114
+ const val = (key, fallback) => this.#envValue(key) ?? explicit[key] ?? fallback
115
+ this.#opts = {
116
+ scope: str('scope', DEFAULT_SCOPE),
117
+ lock: str('lock', DEFAULT_LOCK),
118
+ lockFile: str('lockFile', undefined),
119
+ bundle: str('bundle', DEFAULT_BUNDLE),
120
+ bundleFile: str('bundleFile', undefined),
121
+ resourcesBundleFile: str('resourcesBundleFile', undefined),
122
+ debug: val('debug', false),
123
+ childProcess: val('childProcess', false),
124
+ packageJSON: val('packageJSON', false),
125
+ fs: str('fs', undefined),
126
+ brotliQuality: this.#envValue('brotliQuality') ?? explicit.brotliQuality,
127
+ resources: parseResourcesOption('resources', this.#env.resources !== undefined ? envList(this.#env.resources) : explicit.resources),
128
+ }
129
+ const flush = env.EXODUS_STASIS_SHARD_SIGNAL_FLUSH
130
+ this.#shardSignalFlush = Boolean(flush) && envBool('EXODUS_STASIS_SHARD_SIGNAL_FLUSH', flush)
166
131
 
167
132
  this.#checkInvariants()
168
133
  }
169
134
 
170
- // Per-field validation + cross-field invariants. Constructor (options path) and
171
- // loadConfig (disk path) both call this so the rules live in one place.
135
+ // An option's env value, parsed; undefined when unset.
136
+ #envValue(key) {
137
+ const raw = this.#env[key]
138
+ const { env, parse } = OPTIONS[key]
139
+ return raw === undefined || !parse ? raw : parse(env, raw)
140
+ }
141
+
142
+ #explicitValue(key) {
143
+ const value = this.#explicit[key]
144
+ return value !== undefined && OPTIONS[key].option ? OPTIONS[key].option(value) : value
145
+ }
146
+
172
147
  #checkInvariants() {
173
- assert.ok(VALID_SCOPE.has(this.#scope), `Invalid scope: ${this.#scope}`)
174
- assert.ok(VALID_LOCK.has(this.#lock), `Invalid lock: ${this.#lock}`)
175
- assert.ok(VALID_BUNDLE.has(this.#bundle), `Invalid bundle: ${this.#bundle}`)
176
- assert.equal(typeof this.#debug, 'boolean', 'debug must be a boolean')
177
- assert.equal(typeof this.#childProcess, 'boolean', 'childProcess must be a boolean')
178
- if (this.#fs !== undefined) {
179
- assert.ok(VALID_FS.has(this.#fs), `Invalid fs: ${this.#fs}`)
180
- // --fs patches the fs readers to capture into the bundle (add/replace) or serve them
181
- // from it (load); with any other bundle mode it has nothing to record into or read from.
182
- // Mirrors the CLI's "--fs requires --bundle=(add|replace|load)" guard.
183
- if (this.#bundle !== 'add' && this.#bundle !== 'replace' && this.#bundle !== 'load') {
184
- throw new RangeError(`fs requires bundle=(add|replace|load) (got bundle='${this.#bundle}')`)
148
+ const { lock, lockFile, bundle, bundleFile, resourcesBundleFile, fs, brotliQuality } = this.#opts
149
+ for (const key of ['scope', 'lock', 'bundle', 'debug', 'childProcess', 'packageJSON']) assertOption(key, this.#opts[key])
150
+ if (brotliQuality !== undefined && !isBrotliQuality(brotliQuality)) {
151
+ throw new RangeError(`brotliQuality must be an integer 0..11 (got ${JSON.stringify(brotliQuality)})`)
152
+ }
153
+ if (fs !== undefined) {
154
+ assertOption('fs', fs)
155
+ // --fs captures into the bundle (add/replace) or serves from it (load); other modes have nothing to do.
156
+ if (!['add', 'replace', 'load'].includes(bundle)) {
157
+ throw new RangeError(`fs requires bundle=(add|replace|load) (got bundle='${bundle}')`)
185
158
  }
186
159
  }
187
- if (this.#bundleFile !== undefined) assert.equal(typeof this.#bundleFile, 'string', 'bundleFile must be a string')
188
- if (this.#lockFile !== undefined) {
189
- assert.equal(typeof this.#lockFile, 'string', 'lockFile must be a string')
190
- // lockFile is only meaningful when there IS a lockfile. Lock modes that opt out
191
- // (none / ignore) would silently ignore the path -- catch the misconfig explicitly.
192
- if (this.#lock === 'none' || this.#lock === 'ignore') {
193
- throw new RangeError(`lockFile requires an active lock mode (got lock='${this.#lock}')`)
160
+ if (bundleFile !== undefined) assertOption('bundleFile', bundleFile)
161
+ if (lockFile !== undefined) {
162
+ assertOption('lockFile', lockFile)
163
+ if (lock === 'none' || lock === 'ignore') {
164
+ throw new RangeError(`lockFile requires an active lock mode (got lock='${lock}')`)
194
165
  }
195
166
  }
196
- if (this.#resourcesBundleFile !== undefined) {
197
- assert.equal(typeof this.#resourcesBundleFile, 'string', 'resourcesBundleFile must be a string')
198
- // The split is only meaningful when there IS a bundle to split. With bundle=none / ignore the
199
- // option would be silently inert -- catch the misconfiguration explicitly instead.
200
- if (this.#bundle === 'none' || this.#bundle === 'ignore') {
201
- throw new RangeError(`resourcesBundleFile requires an active bundle mode (got bundle='${this.#bundle}')`)
167
+ if (resourcesBundleFile !== undefined) {
168
+ assertOption('resourcesBundleFile', resourcesBundleFile)
169
+ if (bundle === 'none' || bundle === 'ignore') {
170
+ throw new RangeError(`resourcesBundleFile requires an active bundle mode (got bundle='${bundle}')`)
202
171
  }
203
172
  }
204
173
 
205
- // Cross-path collision checks: the three write targets (lockFile, bundleFile,
206
- // resourcesBundleFile) must each name a distinct on-disk file. Canonicalize via
207
- // resolve() + realpathSync so './x.br' vs 'x.br', and two symlinks to the same
208
- // inode, both compare equal -- a raw string compare would let `./out/x.br` and
209
- // `out/x.br` slip past and the second writer would silently clobber the first.
174
+ // Write targets must be distinct: canonicalize so './x.br' vs 'x.br' and symlinks to one inode compare equal.
210
175
  const claimed = new Map()
211
- for (const [label, value] of [
212
- ['lockFile', this.#lockFile],
213
- ['bundleFile', this.#bundleFile],
214
- ['resourcesBundleFile', this.#resourcesBundleFile],
215
- ]) {
176
+ for (const label of ['lockFile', 'bundleFile', 'resourcesBundleFile']) {
177
+ const value = this.#opts[label]
216
178
  if (value === undefined) continue
217
- const canonical = canonicalizePath(value)
179
+ const canonical = canonicalizePath(value, this.#host)
218
180
  if (claimed.has(canonical)) {
219
181
  throw new RangeError(`${label} '${value}' targets the same file as ${claimed.get(canonical)}; each must be a distinct path`)
220
182
  }
221
183
  claimed.set(canonical, label)
222
184
  }
223
185
 
224
- // bundle=load needs a trust root for source bytes: frozen pins each file's sha512 in
225
- // the lockfile and we cross-check it on load; otherwise the bundle is itself
226
- // authoritative -- lock=none with no lockfile on disk, or lock=ignore with a lockfile
227
- // deliberately bypassed.
228
- // WARNING: the lockfile attests source bytes, entries, module identity, and
229
- // (when it records them) resolutions and loader formats. Lockfiles predating
230
- // a given attestation cover only what they recorded (bytes at minimum).
231
- if (this.#bundle === 'load' && this.#lock !== 'frozen' && this.#lock !== 'none' && this.#lock !== 'ignore') {
186
+ // bundle=load needs a trust root: frozen pins each file's sha512, else the bundle itself is it (none/ignore).
187
+ if (bundle === 'load' && !['frozen', 'none', 'ignore'].includes(lock)) {
232
188
  throw new RangeError('bundle=load is incompatible with lock=(add|replace)')
233
189
  }
234
190
 
235
- // bundle=frozen places no constraint on lock: unlike load it never *serves* the
236
- // bundle's bytes, it reads each file from disk and verifies it against the bundle's
237
- // own recorded bytes/resolutions/formats (the bundle is itself the trust root, so it
238
- // needs no sibling lockfile -- it "operates as a lockfile"). It composes with any lock
239
- // mode, and (being a real bundle) satisfies the "needs a lockfile or a bundle" rule
240
- // below -- which only rejects leaving both unset.
241
- if (this.#lock === 'none' && this.#bundle === 'none') {
191
+ // bundle=frozen deliberately constrains no lock mode: it verifies disk against the bundle, its own trust root.
192
+ if (lock === 'none' && bundle === 'none') {
242
193
  throw new RangeError('stasis needs a lockfile or a bundle: set lock or bundle')
243
194
  }
244
195
  }
245
196
 
246
197
  loadConfig(json) {
247
- const {
248
- scope = this.#scope,
249
- lock = this.#lock,
250
- bundle = this.#bundle,
251
- bundleFile = this.#bundleFile,
252
- resourcesBundleFile = this.#resourcesBundleFile,
253
- debug = this.#debug,
254
- childProcess = this.#childProcess,
255
- fs = this.#fs,
256
- resources,
257
- ...rest
258
- } = JSON.parse(json)
259
- assert.equal(Object.keys(rest).length, 0)
260
- this.#scope = scope
261
- this.#lock = lock
262
- this.#bundle = bundle
263
- // Coerce '' -> undefined to match the constructor: an empty-string path is "unset"
264
- // everywhere downstream (State consumes bundleFile truthily), but #checkInvariants would
265
- // otherwise resolve('') -> cwd and claim it as a write target.
266
- this.#bundleFile = bundleFile || undefined
267
- this.#resourcesBundleFile = resourcesBundleFile || undefined
268
- this.#debug = debug
269
- this.#childProcess = childProcess
270
- this.#fs = fs
271
- if (resources !== undefined) this.#resources = parseResourcesOption('stasis.config.json', resources)
198
+ const config = JSON.parse(json)
199
+ const keys = Object.keys(config)
200
+ assert.equal(keys.filter((key) => !CONFIG_FILE_KEYS.includes(key)).length, 0)
201
+ for (const key of keys) {
202
+ if (key === 'resources') this.#opts.resources = parseResourcesOption('stasis.config.json', config.resources)
203
+ // '' -> undefined like the constructor: otherwise canonicalizePath('') claims cwd as a write target.
204
+ else if (key === 'bundleFile' || key === 'resourcesBundleFile') this.#opts[key] = config[key] || undefined
205
+ else this.#opts[key] = config[key]
206
+ }
272
207
  this.#checkInvariants()
273
208
 
274
209
  try {
275
- if (this.#env.scope !== undefined) assert.equal(this.#scope, this.#env.scope)
276
- if (this.#env.lock !== undefined) assert.equal(this.#lock, this.#env.lock)
277
- if (this.#env.bundle !== undefined) assert.equal(this.#bundle, this.#env.bundle)
278
- if (this.#env.bundleFile !== undefined) assert.equal(this.#bundleFile, this.#env.bundleFile)
279
- if (this.#env.resourcesBundleFile !== undefined) assert.equal(this.#resourcesBundleFile, this.#env.resourcesBundleFile)
280
- if (this.#env.debug !== undefined) assert.equal(this.#debug, envBool('EXODUS_STASIS_DEBUG', this.#env.debug))
281
- if (this.#env.childProcess !== undefined) assert.equal(this.#childProcess, envBool('EXODUS_STASIS_CHILD_PROCESS', this.#env.childProcess))
282
- if (this.#env.fs !== undefined) assert.equal(this.#fs, this.#env.fs)
283
- if (this.#env.resources !== undefined) {
284
- assert.ok(extSetsEqual(this.#resources, parseResourcesOption('env', envList(this.#env.resources))),
285
- 'resources in stasis.config.json must match EXODUS_STASIS_RESOURCES')
210
+ for (const key of CONFIG_FILE_KEYS) {
211
+ if (this.#env[key] !== undefined) {
212
+ assertSame(key, this.#opts[key], this.#envValue(key), 'resources in stasis.config.json must match EXODUS_STASIS_RESOURCES')
213
+ }
286
214
  }
287
- // Explicit constructor options are equally authoritative: an explicit
288
- // `--scope=full` shouldn't be silently overridden by an on-disk
289
- // `{"scope":"node_modules"}`. The asserts mirror the env block above.
290
- if (this.#explicit.scope !== undefined) assert.equal(this.#scope, this.#explicit.scope)
291
- if (this.#explicit.lock !== undefined) assert.equal(this.#lock, this.#explicit.lock)
292
- if (this.#explicit.bundle !== undefined) assert.equal(this.#bundle, this.#explicit.bundle)
293
- if (this.#explicit.bundleFile !== undefined) assert.equal(this.#bundleFile, this.#explicit.bundleFile)
294
- if (this.#explicit.resourcesBundleFile !== undefined) assert.equal(this.#resourcesBundleFile, this.#explicit.resourcesBundleFile)
295
- if (this.#explicit.debug !== undefined) assert.equal(this.#debug, this.#explicit.debug)
296
- if (this.#explicit.childProcess !== undefined) assert.equal(this.#childProcess, this.#explicit.childProcess)
297
- if (this.#explicit.fs !== undefined) assert.equal(this.#fs, this.#explicit.fs)
298
- if (this.#explicit.resources !== undefined) {
299
- assert.ok(extSetsEqual(this.#resources, parseResourcesOption('options', this.#explicit.resources)),
300
- 'resources in stasis.config.json must match the resources option')
215
+ // Explicit constructor options are equally authoritative: an on-disk config can't override --scope=full.
216
+ for (const key of CONFIG_FILE_KEYS) {
217
+ if (this.#explicit[key] !== undefined) {
218
+ assertSame(key, this.#opts[key], this.#explicitValue(key), 'resources in stasis.config.json must match the resources option')
219
+ }
301
220
  }
302
221
  } catch (cause) {
303
222
  throw new Error('Flags/env can not override stasis.config.json', { cause })
@@ -305,129 +224,124 @@ export class Config {
305
224
  }
306
225
 
307
226
  get bundleFile() {
308
- return this.#bundleFile
227
+ return this.#opts.bundleFile
309
228
  }
310
229
 
311
- // When set, State reads/writes the lockfile at this exact path instead of
312
- // discovering `stasis.lock.json` at the project root. Set via the CLI,
313
- // `EXODUS_STASIS_LOCK_FILE`, or direct State construction; bundler plugins
314
- // can't set it (they always share the ambient lockfile). Unset -> default
315
- // discovery applies.
230
+ // Exact lockfile path, bypassing `stasis.lock.json` discovery; bundler plugins can't set it.
316
231
  get lockFile() {
317
- return this.#lockFile
232
+ return this.#opts.lockFile
318
233
  }
319
234
 
320
- // When set, State.write() emits resources to this file and code-only to bundleFile;
321
- // bundle=load reads both. Unset is the default unified-bundle behavior.
235
+ // When set, resources go to this file and code-only to bundleFile; bundle=load reads both.
322
236
  get resourcesBundleFile() {
323
- return this.#resourcesBundleFile
237
+ return this.#opts.resourcesBundleFile
324
238
  }
325
239
 
326
- // The parsed `resources` allowlist: a Set of lowercase extensions or extensionless
327
- // filenames that classifyExtension treats as asset payloads. Drives both the plugins'
328
- // per-import classification and State's `--fs` capture, so the two share one list.
329
- // Empty Set when no allowlist was configured (option or EXODUS_STASIS_RESOURCES).
240
+ // Set of lowercase extensions/filenames treated as asset payloads.
330
241
  get resources() {
331
- return this.#resources
242
+ return this.#opts.resources
332
243
  }
333
244
 
334
245
  get debug() {
335
- return this.#debug
246
+ return this.#opts.debug
336
247
  }
337
248
 
338
- // Opt-in (CLI --child-process / EXODUS_STASIS_CHILD_PROCESS / "childProcess": true in
339
- // stasis.config.json): enable cross-process capture forwarding. A forked child (e.g. a
340
- // Metro transform worker) writes a shard of what it captured into a root-owned dir, and
341
- // the root merges it before writing -- so files only a child loads (a worker's babel
342
- // toolchain) are attested. Off by default: the shard dir is a process-coordination channel,
343
- // so it's only created when explicitly enabled. Not attested (not in `values`), like debug.
249
+ // Opt-in cross-process capture forwarding: a forked child writes a shard the root merges. Not attested.
344
250
  get childProcess() {
345
- return this.#childProcess
251
+ return this.#opts.childProcess
252
+ }
253
+
254
+ // Opt-in: bundle every bundled module's package.json even if the run never reached it. Not attested.
255
+ get packageJSON() {
256
+ return this.#opts.packageJSON
346
257
  }
347
258
 
348
- // The --fs hook mode: 'sync' patches the sync fs readers, 'async' additionally patches
349
- // their async (callback + fs.promises) counterparts, undefined leaves fs untouched. Set via
350
- // --fs / EXODUS_STASIS_FS / "fs" in stasis.config.json; the runtime loader (hooks.js) reads
351
- // this on State init to decide whether (and how) to install the fs hooks. Not serialized --
352
- // a how-to-run flag like debug/childProcess, not an attested property of the bundle.
259
+ // Env-only: a capturing child flushes its shard on SIGTERM (jest-worker force-kills Metro workers),
260
+ // then re-delivers the signal. Not a user option, not attested.
261
+ get shardSignalFlush() {
262
+ return this.#shardSignalFlush
263
+ }
264
+
265
+ // --fs hook mode: 'sync' patches the sync readers, 'async' both; undefined leaves fs untouched. Not serialized.
353
266
  get fs() {
354
- return this.#fs
267
+ return this.#opts.fs
268
+ }
269
+
270
+ // Brotli quality (0..11); undefined -> DEFAULT_BROTLI_QUALITY. Not serialized -- output decompresses identically.
271
+ get brotliQuality() {
272
+ return this.#opts.brotliQuality
355
273
  }
356
274
 
357
275
  get values() {
358
- return { scope: this.#scope }
276
+ return { scope: this.#opts.scope }
359
277
  }
360
278
 
361
279
  get bundle() {
362
- return this.#bundle !== 'none' && this.#bundle !== 'ignore'
280
+ return this.#opts.bundle !== 'none' && this.#opts.bundle !== 'ignore'
363
281
  }
364
282
 
365
283
  get bundleMode() {
366
- return this.#bundle
284
+ return this.#opts.bundle
367
285
  }
368
286
 
369
287
  get ignoreBundle() {
370
- return this.#bundle === 'ignore'
288
+ return this.#opts.bundle === 'ignore'
371
289
  }
372
290
 
373
291
  get writeBundle() {
374
- return this.#bundle === 'add' || this.#bundle === 'replace'
292
+ return this.#opts.bundle === 'add' || this.#opts.bundle === 'replace'
375
293
  }
376
294
 
377
295
  get replaceBundle() {
378
- return this.#bundle === 'replace'
296
+ return this.#opts.bundle === 'replace'
379
297
  }
380
298
 
381
299
  get loadBundle() {
382
- return this.#bundle === 'load'
300
+ return this.#opts.bundle === 'load'
383
301
  }
384
302
 
385
- // bundle=frozen: the bundle is a read-only attestation, like a frozen lockfile.
386
- // It is loaded (its bytes/resolutions/entries/modules become the attested set) but
387
- // never rewritten, and every file/resolution observed from disk is checked against
388
- // it. Distinct from load (which serves bytes from the bundle instead of reading disk)
389
- // and from add (which loads-then-rewrites and tolerates new files).
303
+ // bundle=frozen: loaded, never rewritten, and disk is checked against it (load serves bytes instead).
390
304
  get frozenBundle() {
391
- return this.#bundle === 'frozen'
305
+ return this.#opts.bundle === 'frozen'
392
306
  }
393
307
 
394
308
  get full() {
395
- return this.#scope === 'full'
309
+ return this.#opts.scope === 'full'
396
310
  }
397
311
 
398
312
  get frozen() {
399
- return this.#lock === 'frozen'
313
+ return this.#opts.lock === 'frozen'
400
314
  }
401
315
 
402
316
  get useLockfile() {
403
- return this.#lock !== 'none' && this.#lock !== 'ignore'
317
+ return this.#opts.lock !== 'none' && this.#opts.lock !== 'ignore'
404
318
  }
405
319
 
406
320
  get ignoreLockfile() {
407
- return this.#lock === 'ignore'
321
+ return this.#opts.lock === 'ignore'
408
322
  }
409
323
 
410
324
  get writeLockfile() {
411
- return this.#lock === 'add' || this.#lock === 'replace'
325
+ return this.#opts.lock === 'add' || this.#opts.lock === 'replace'
412
326
  }
413
327
 
414
328
  get replaceLockfile() {
415
- return this.#lock === 'replace'
329
+ return this.#opts.lock === 'replace'
416
330
  }
417
331
 
418
332
  get scope() {
419
- return this.#scope
333
+ return this.#opts.scope
420
334
  }
421
335
 
422
336
  get lock() {
423
- return this.#lock
337
+ return this.#opts.lock
424
338
  }
425
339
 
426
340
  get json() {
427
- const data = { scope: this.#scope, lock: this.#lock, bundle: this.#bundle }
428
- // resources persists like scope/lock/bundle (a project-level declaration), but only
429
- // when non-empty so configs without an allowlist serialize byte-identically as before.
430
- if (this.#resources.size > 0) data.resources = [...this.#resources].toSorted()
341
+ const { scope, lock, bundle, resources } = this.#opts
342
+ const data = { scope, lock, bundle }
343
+ // Only serialize `resources` when non-empty, so configs without an allowlist stay byte-identical.
344
+ if (resources.size > 0) data.resources = [...resources].toSorted()
431
345
  return JSON.stringify(data, undefined, 2) + '\n'
432
346
  }
433
347
  }