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

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.
@@ -8,6 +8,7 @@ import { basename, resolve } from 'node:path'
8
8
  import { existsSync, realpathSync } from 'node:fs'
9
9
  import { constants as osConstants } from 'node:os'
10
10
  import assert from 'node:assert/strict'
11
+ import { parseBrotliQuality } from '../src/util.js'
11
12
  import pkg from '../package.json' with { type: 'json' }
12
13
 
13
14
  const argv = [...process.argv]
@@ -20,7 +21,7 @@ assert(basename(jsname) === 'stasis-core' || pathsEqual(jsname, fileURLToPath(im
20
21
 
21
22
  function usage(prefix = '') {
22
23
  console.error(`${prefix}\nUsage:
23
- stasis-core run --lock=(add|replace|frozen|ignore) [--bundle=(add|replace|load|frozen|ignore)] [--bundle-file=path/to/bundle.br] [--resources-bundle-file=path/to/resources.br] [--dependencies] [--child-process] [--fs=(sync|async)] [--resources=ext,ext] path/to/file.js ...
24
+ stasis-core run --lock=(add|replace|frozen|ignore) [--bundle=(add|replace|load|frozen|ignore)] [--bundle-file=path/to/bundle.br] [--resources-bundle-file=path/to/resources.br] [--dependencies] [--child-process] [--fs=(sync|async)] [--resources=ext,ext] [--brotli-quality=0..11] path/to/file.js ...
24
25
  stasis-core prune [path/to/project]
25
26
  `.trim())
26
27
  process.exit(1)
@@ -39,7 +40,7 @@ if (command === '-v' || command === '--version') {
39
40
  process.exit(0)
40
41
  } else if (command === 'run') {
41
42
  const flags = []
42
- const valueFlags = new Set(['--bundle', '--bundle-file', '--resources-bundle-file', '--lock', '--resources'])
43
+ const valueFlags = new Set(['--bundle', '--bundle-file', '--resources-bundle-file', '--lock', '--resources', '--brotli-quality'])
43
44
  while (argv.length > 0 && (argv[0].startsWith('-') || valueFlags.has(flags.at(-1)))) {
44
45
  flags.push(argv.shift())
45
46
  }
@@ -54,6 +55,7 @@ if (command === '-v' || command === '--version') {
54
55
  'child-process': { type: 'boolean' },
55
56
  fs: { type: 'string' },
56
57
  resources: { type: 'string' },
58
+ 'brotli-quality': { type: 'string' },
57
59
  }
58
60
 
59
61
  let values
@@ -88,10 +90,19 @@ if (command === '-v' || command === '--version') {
88
90
  // --resources: comma-separated extension/filename allowlist for `--fs` resource captures
89
91
  // (e.g. png,svg,LICENSE). The child's Config validates each entry via parseResourcesOption.
90
92
  const resources = values.resources ?? ''
93
+ // --brotli-quality: bundle compression quality (0..11; unset = brotli's default 11).
94
+ let brotliQuality
95
+ if (values['brotli-quality'] !== undefined) {
96
+ try {
97
+ brotliQuality = parseBrotliQuality('--brotli-quality', values['brotli-quality'])
98
+ } catch (cause) {
99
+ usage(`Error: ${cause.message}`)
100
+ }
101
+ }
91
102
  // --child-process: forward forked-child (e.g. Metro transform worker) capture to the root
92
103
  // via per-pid shards. Opt-in -- it stands up a process-coordination channel, off by default.
93
104
  const childProcess = values['child-process'] ? '1' : ''
94
- console.warn('[stasis-core] Running stasis with config:', { lock, scope, bundle, ...(bundleFile && { bundleFile }), ...(resourcesBundleFile && { resourcesBundleFile }), ...(childProcess && { childProcess: true }), ...(values.fs && { fs: values.fs }), ...(resources && { resources }) })
105
+ console.warn('[stasis-core] Running stasis with config:', { lock, scope, bundle, ...(bundleFile && { bundleFile }), ...(resourcesBundleFile && { resourcesBundleFile }), ...(childProcess && { childProcess: true }), ...(values.fs && { fs: values.fs }), ...(resources && { resources }), ...(brotliQuality !== undefined && { brotliQuality }) })
95
106
  if (debug) console.warn(`[stasis-core] Warning: stasis debug mode active`)
96
107
  setEnv('EXODUS_STASIS_LOCK', lock)
97
108
  setEnv('EXODUS_STASIS_SCOPE', scope)
@@ -102,6 +113,9 @@ if (command === '-v' || command === '--version') {
102
113
  setEnv('EXODUS_STASIS_CHILD_PROCESS', childProcess)
103
114
  setEnv('EXODUS_STASIS_FS', captureFs)
104
115
  setEnv('EXODUS_STASIS_RESOURCES', resources)
116
+ // Only set when given, so an ambient EXODUS_STASIS_BROTLI_QUALITY still passes through
117
+ // to the child (an unconditional setEnv('') would reject it as a conflict).
118
+ if (brotliQuality !== undefined) setEnv('EXODUS_STASIS_BROTLI_QUALITY', String(brotliQuality))
105
119
  const nodeArgs = ['--import', import.meta.resolve('../src/loader.js')]
106
120
  const child = spawn(process.execPath, [...nodeArgs, ...argv], { stdio: 'inherit' })
107
121
  const [code, signal] = await once(child, 'close')
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@exodus/stasis-core",
3
- "version": "1.0.0-beta.1",
3
+ "version": "1.0.0-beta.2",
4
4
  "description": "Zero-dependency stasis runtime",
5
5
  "type": "module",
6
6
  "exports": {
package/src/brotli.js CHANGED
@@ -1,21 +1,28 @@
1
1
  import { constants as zlibConstants } from 'node:zlib'
2
2
 
3
- import { assert } from './util.js'
3
+ import { assert, isBrotliQuality, parseBrotliQuality } from './util.js'
4
4
 
5
5
  // Brotli's default quality is 11 (max) and the encoder is superlinear in input
6
- // size, so on a multi-MB source bundle it dominates write time. Tests that
7
- // bundle real-world dependency trees can override this via the env var to keep
8
- // runs fast; the output is still a valid .br at any quality. Production code
9
- // pays the default cost in exchange for the best ratio.
6
+ // size, so on a multi-MB source bundle it dominates write time. The quality is
7
+ // tunable via `quality` (an integer 0..11, typically config.brotliQuality) or the
8
+ // env var -- which must agree when both are set; the output is still a valid .br
9
+ // at any quality. Production code pays the default cost for the best ratio.
10
10
  //
11
11
  // Kept out of `util.js` so that importing the generic helpers there (`sortPaths`,
12
12
  // `assertRealPathWithinBase`, …) doesn't transitively load `node:zlib`. Only the
13
13
  // code that actually compresses a bundle (`state.js`, `stasis bundle`) reaches
14
14
  // for this, and that code already imports zlib directly.
15
- export function brotliOptions() {
15
+ export function brotliOptions(quality) {
16
+ if (quality !== undefined) {
17
+ assert(isBrotliQuality(quality), `brotli quality must be an integer 0..11, got ${quality}`)
18
+ }
16
19
  const raw = process.env.EXODUS_STASIS_BROTLI_QUALITY
17
- if (!raw) return undefined
18
- const n = Number(raw)
19
- assert(Number.isInteger(n) && n >= 0 && n <= 11, `EXODUS_STASIS_BROTLI_QUALITY must be an integer 0..11, got ${raw}`)
20
- return { params: { [zlibConstants.BROTLI_PARAM_QUALITY]: n } }
20
+ if (raw) {
21
+ const n = parseBrotliQuality('EXODUS_STASIS_BROTLI_QUALITY', raw)
22
+ assert(quality === undefined || quality === n,
23
+ `brotli quality ${quality} conflicts with EXODUS_STASIS_BROTLI_QUALITY=${raw}`)
24
+ quality = n
25
+ }
26
+ if (quality === undefined) return undefined
27
+ return { params: { [zlibConstants.BROTLI_PARAM_QUALITY]: quality } }
21
28
  }
package/src/bundle.js CHANGED
@@ -113,7 +113,13 @@ export class Bundle {
113
113
  for (const [file, format] of Object.entries(json.formats)) {
114
114
  assert(!posixPathEscapes(file))
115
115
  assert(KNOWN_FORMATS.has(format), `unknown format '${format}' for ${file}`)
116
- formats.set(file, format)
116
+ // The project root's `directory` listing is keyed '.' -- bundles written before
117
+ // that normalization keyed it '' (see moduleFileKey), which no lookup ever hits
118
+ // again at load. Normalize on parse so those artifacts keep serving; the alias
119
+ // makes '' and '.' the SAME key, so both appearing is a duplicate -- fail closed.
120
+ const key = file === '' ? '.' : file
121
+ assert(!formats.has(key), `duplicate format key '${key}'`)
122
+ formats.set(key, format)
117
123
  }
118
124
 
119
125
  const modules = new Map()
package/src/config.js CHANGED
@@ -1,7 +1,7 @@
1
1
  import assert from 'node:assert/strict'
2
2
 
3
3
  import { canonicalizePath } from './state-util.js'
4
- import { extSetsEqual, parseResourcesOption } from './util.js'
4
+ import { extSetsEqual, isBrotliQuality, parseBrotliQuality, parseResourcesOption } from './util.js'
5
5
 
6
6
  const VALID_SCOPE = new Set(['node_modules', 'full'])
7
7
  const VALID_LOCK = new Set(['none', 'ignore', 'add', 'replace', 'frozen'])
@@ -86,10 +86,12 @@ export class Config {
86
86
  #resources
87
87
  #debug
88
88
  #childProcess
89
+ #shardSignalFlush
89
90
  #fs
91
+ #brotliQuality
90
92
 
91
93
  // Options match the CLI flags (scope/lock/lockFile/bundle/bundleFile/resourcesBundleFile/debug/
92
- // resources/childProcess/fs).
94
+ // resources/childProcess/fs/brotliQuality).
93
95
  // Env vars take effect at construction time; if both env and an option are set they must
94
96
  // agree. Likewise, any explicit constructor option is treated as authoritative: a later
95
97
  // `loadConfig` call (which reads stasis.config.json) must agree with it -- the alternative
@@ -97,9 +99,9 @@ export class Config {
97
99
  // was a footgun the CLI couldn't detect, since the flag was happily accepted
98
100
  // and then quietly ignored.
99
101
  constructor(options = {}) {
100
- const { scope, lock, lockFile, bundle, bundleFile, resourcesBundleFile, debug, resources, childProcess, fs, ...rest } = options
102
+ const { scope, lock, lockFile, bundle, bundleFile, resourcesBundleFile, debug, resources, childProcess, fs, brotliQuality, ...rest } = options
101
103
  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 }
104
+ this.#explicit = { scope, lock, lockFile, bundle, bundleFile, resourcesBundleFile, debug, resources, childProcess, fs, brotliQuality }
103
105
 
104
106
  this.#env = {
105
107
  scope: process.env.EXODUS_STASIS_SCOPE || undefined,
@@ -111,7 +113,9 @@ export class Config {
111
113
  debug: process.env.EXODUS_STASIS_DEBUG || undefined,
112
114
  resources: process.env.EXODUS_STASIS_RESOURCES || undefined,
113
115
  childProcess: process.env.EXODUS_STASIS_CHILD_PROCESS || undefined,
116
+ shardSignalFlush: process.env.EXODUS_STASIS_SHARD_SIGNAL_FLUSH || undefined,
114
117
  fs: process.env.EXODUS_STASIS_FS || undefined,
118
+ brotliQuality: process.env.EXODUS_STASIS_BROTLI_QUALITY || undefined,
115
119
  }
116
120
 
117
121
  try {
@@ -134,6 +138,9 @@ export class Config {
134
138
  assert.equal(envBool('EXODUS_STASIS_CHILD_PROCESS', this.#env.childProcess), childProcess)
135
139
  }
136
140
  if (this.#env.fs !== undefined && fs !== undefined) assert.equal(this.#env.fs, fs)
141
+ if (this.#env.brotliQuality !== undefined && brotliQuality !== undefined) {
142
+ assert.equal(parseBrotliQuality('EXODUS_STASIS_BROTLI_QUALITY', this.#env.brotliQuality), brotliQuality)
143
+ }
137
144
  // Compare parsed sets, not the raw strings: ['png','svg'] and 'svg,png' are the
138
145
  // same allowlist. An empty/unset env var is "no env opinion" (handled by `||
139
146
  // undefined` above), so this only fires on two genuinely different non-empty lists.
@@ -155,8 +162,17 @@ export class Config {
155
162
  this.#resourcesBundleFile = this.#env.resourcesBundleFile || resourcesBundleFile || undefined
156
163
  this.#debug = this.#env.debug !== undefined ? envBool('EXODUS_STASIS_DEBUG', this.#env.debug) : (debug ?? false)
157
164
  this.#childProcess = this.#env.childProcess !== undefined ? envBool('EXODUS_STASIS_CHILD_PROCESS', this.#env.childProcess) : (childProcess ?? false)
165
+ // Env-only (no option, no stasis.config.json key): shard-channel plumbing a parent
166
+ // process sets for its descendants, not a user-facing knob -- see the getter.
167
+ this.#shardSignalFlush = this.#env.shardSignalFlush !== undefined
168
+ ? envBool('EXODUS_STASIS_SHARD_SIGNAL_FLUSH', this.#env.shardSignalFlush)
169
+ : false
158
170
  // env wins over the option, like scope/lock/bundle; undefined means "fs untouched" (off).
159
171
  this.#fs = this.#env.fs || fs || undefined
172
+ // env wins over the option; no `||` chaining -- 0 is a valid quality and falsy.
173
+ this.#brotliQuality = this.#env.brotliQuality !== undefined
174
+ ? parseBrotliQuality('EXODUS_STASIS_BROTLI_QUALITY', this.#env.brotliQuality)
175
+ : brotliQuality
160
176
  // env wins over the option (it's the process-wide signal); parseResourcesOption
161
177
  // normalizes both to a Set of lowercase extensions/filenames, or empty when neither set.
162
178
  this.#resources = parseResourcesOption(
@@ -175,6 +191,11 @@ export class Config {
175
191
  assert.ok(VALID_BUNDLE.has(this.#bundle), `Invalid bundle: ${this.#bundle}`)
176
192
  assert.equal(typeof this.#debug, 'boolean', 'debug must be a boolean')
177
193
  assert.equal(typeof this.#childProcess, 'boolean', 'childProcess must be a boolean')
194
+ // A write-side knob; like bundleFile, inert-but-harmless under read-only modes
195
+ // (the same stasis.config.json serves capture and load runs).
196
+ if (this.#brotliQuality !== undefined && !isBrotliQuality(this.#brotliQuality)) {
197
+ throw new RangeError(`brotliQuality must be an integer 0..11 (got ${JSON.stringify(this.#brotliQuality)})`)
198
+ }
178
199
  if (this.#fs !== undefined) {
179
200
  assert.ok(VALID_FS.has(this.#fs), `Invalid fs: ${this.#fs}`)
180
201
  // --fs patches the fs readers to capture into the bundle (add/replace) or serve them
@@ -253,6 +274,7 @@ export class Config {
253
274
  debug = this.#debug,
254
275
  childProcess = this.#childProcess,
255
276
  fs = this.#fs,
277
+ brotliQuality = this.#brotliQuality,
256
278
  resources,
257
279
  ...rest
258
280
  } = JSON.parse(json)
@@ -268,6 +290,7 @@ export class Config {
268
290
  this.#debug = debug
269
291
  this.#childProcess = childProcess
270
292
  this.#fs = fs
293
+ this.#brotliQuality = brotliQuality
271
294
  if (resources !== undefined) this.#resources = parseResourcesOption('stasis.config.json', resources)
272
295
  this.#checkInvariants()
273
296
 
@@ -280,6 +303,9 @@ export class Config {
280
303
  if (this.#env.debug !== undefined) assert.equal(this.#debug, envBool('EXODUS_STASIS_DEBUG', this.#env.debug))
281
304
  if (this.#env.childProcess !== undefined) assert.equal(this.#childProcess, envBool('EXODUS_STASIS_CHILD_PROCESS', this.#env.childProcess))
282
305
  if (this.#env.fs !== undefined) assert.equal(this.#fs, this.#env.fs)
306
+ if (this.#env.brotliQuality !== undefined) {
307
+ assert.equal(this.#brotliQuality, parseBrotliQuality('EXODUS_STASIS_BROTLI_QUALITY', this.#env.brotliQuality))
308
+ }
283
309
  if (this.#env.resources !== undefined) {
284
310
  assert.ok(extSetsEqual(this.#resources, parseResourcesOption('env', envList(this.#env.resources))),
285
311
  'resources in stasis.config.json must match EXODUS_STASIS_RESOURCES')
@@ -295,6 +321,7 @@ export class Config {
295
321
  if (this.#explicit.debug !== undefined) assert.equal(this.#debug, this.#explicit.debug)
296
322
  if (this.#explicit.childProcess !== undefined) assert.equal(this.#childProcess, this.#explicit.childProcess)
297
323
  if (this.#explicit.fs !== undefined) assert.equal(this.#fs, this.#explicit.fs)
324
+ if (this.#explicit.brotliQuality !== undefined) assert.equal(this.#brotliQuality, this.#explicit.brotliQuality)
298
325
  if (this.#explicit.resources !== undefined) {
299
326
  assert.ok(extSetsEqual(this.#resources, parseResourcesOption('options', this.#explicit.resources)),
300
327
  'resources in stasis.config.json must match the resources option')
@@ -345,6 +372,21 @@ export class Config {
345
372
  return this.#childProcess
346
373
  }
347
374
 
375
+ // Opt-in (EXODUS_STASIS_SHARD_SIGNAL_FLUSH, env-only): a capturing CHILD flushes its
376
+ // shard when ended by SIGTERM, then re-delivers the signal (hooks.js). Set on
377
+ // process.env by StasisMetro's capture wiring, so every capturing child the build forks
378
+ // after config time inherits it -- Metro's transform workers are the intended audience:
379
+ // jest-worker force-kills a worker whose event loop doesn't drain within 500ms of its
380
+ // END message, which would otherwise silently drop the worker's shard.
381
+ // Deliberately NOT a global default (a signal listener changes a child's default-kill
382
+ // disposition -- the user's domain in arbitrary children) and NOT a user option: it is
383
+ // channel plumbing like EXODUS_STASIS_SHARD_DIR/_KEY, but parsed strictly through
384
+ // envBool like every other boolean toggle so '0'/'false' disable rather than enable.
385
+ // Not attested (not in `values`), like childProcess.
386
+ get shardSignalFlush() {
387
+ return this.#shardSignalFlush
388
+ }
389
+
348
390
  // The --fs hook mode: 'sync' patches the sync fs readers, 'async' additionally patches
349
391
  // their async (callback + fs.promises) counterparts, undefined leaves fs untouched. Set via
350
392
  // --fs / EXODUS_STASIS_FS / "fs" in stasis.config.json; the runtime loader (hooks.js) reads
@@ -354,6 +396,13 @@ export class Config {
354
396
  return this.#fs
355
397
  }
356
398
 
399
+ // Brotli quality (integer 0..11) for bundle writes; undefined -> brotli's default (11,
400
+ // max). State.write() forwards this to brotliOptions(). Not serialized -- a how-to-write
401
+ // flag like debug/fs; the bundle's decompressed content is identical at any quality.
402
+ get brotliQuality() {
403
+ return this.#brotliQuality
404
+ }
405
+
357
406
  get values() {
358
407
  return { scope: this.#scope }
359
408
  }
package/src/fs.js CHANGED
@@ -2,7 +2,8 @@
2
2
  // the filesystem readers
3
3
  // fs.readFileSync, fs.readdirSync, fs.lstatSync, fs.statSync so that, alongside the
4
4
  // module graph the loader hooks already capture, a program's explicit file/directory
5
- // reads are recorded into the bundle (bundle=add|replace) and served back from it
5
+ // reads -- and the KIND (file vs directory) of the paths it lstat/stats -- are
6
+ // recorded into the bundle (bundle=add|replace) and served back from it
6
7
  // (bundle=load). Alongside the readers, the existence/canonical-path PROBES existsSync /
7
8
  // accessSync / realpathSync are served (load mode) so a tool that checks a file before
8
9
  // reading it finds a bundle-only file -- see the existsSync/accessSync/realpathSync bullet.
@@ -31,17 +32,27 @@
31
32
  // - readFileSync: the optional second argument (an `encoding` string, or an
32
33
  // options object with `encoding`) is honoured; the raw bytes are what we
33
34
  // capture/serve and `encoding` is applied on the way out.
34
- // - lstatSync / statSync: serve-only, bundle=load, single-argument form. For a
35
- // recorded path they return a Stats-like object whose isFile()/isDirectory() come
35
+ // - lstatSync / statSync: single-argument form, captured AND served -- but ONLY the
36
+ // path's kind, i.e. the type getters isFile()/isDirectory(); full Stats fields are
37
+ // never attested. CAPTURE (bundle=add|replace): the real call runs first, so the
38
+ // caller always gets the genuine Stats (and genuine errors); the observed kind is
39
+ // then recorded as a PAYLOAD-FREE stat record ('stat:file'/'stat:directory' in
40
+ // `formats` -- no bytes, no hash), so a stat-ONLY path -- never read, readdir'd,
41
+ // or imported -- still answers at load. A path that is neither a regular file nor
42
+ // a directory (a symlink under lstat, a socket, a FIFO, ...) isn't modelled and
43
+ // records nothing. SERVE (bundle=load): for a recorded path they return a
44
+ // Stats-like object whose isFile()/isDirectory() come
36
45
  // from the bundle (the common existence check); every other member is the real
37
46
  // stat while the file is still on disk, and a benign synthetic default (0 / epoch
38
47
  // / file-or-dir mode) once it's gone -- so fs wrappers that read more than
39
48
  // isFile()/isDirectory() (graceful-fs reads stats.uid/gid) keep working under
40
- // bundle=load instead of re-throwing ENOENT. Not patched in capture mode (the file
41
- // is on disk there, so the real Stats is correct), except to report a skipped
42
- // source-map sidecar as absent (next bullet). statSync vs lstatSync differ only in
43
- // symlink following, which matters solely for that on-disk passthrough -- each falls
44
- // back to its own real implementation.
49
+ // bundle=load instead of re-throwing ENOENT. A skipped
50
+ // source-map sidecar is reported absent in both modes (next bullet). statSync vs
51
+ // lstatSync differ only in symlink following, which matters for the real-call
52
+ // paths (passthrough, capture, present-on-disk serve) -- each uses its own real
53
+ // implementation, and a stat of an in-root symlink records the TARGET's kind
54
+ // under the requested path (keyed exactly like a byte read of that path would
55
+ // be) while an lstat of one records nothing.
45
56
  // - existsSync / accessSync / realpathSync (+ their async/promise forms under =async):
46
57
  // existence/canonical-path PROBES, serve-only and bundle=load only. A path the bundle
47
58
  // records answers existent / accessible (read-only: F_OK/R_OK, while W_OK/X_OK defer) /
@@ -57,7 +68,9 @@
57
68
  // module loader). Because these are serve-only (never captured), a file that is ONLY
58
69
  // existence-probed -- never read or imported -- isn't recorded, so its probe falls
59
70
  // through to disk on load; babel.config.js is fine because it is also require()d, hence
60
- // recorded. realpathSync returns the real (symlink-resolved) path while the file is on
71
+ // recorded. (An lstatSync/statSync of a path, by contrast, DOES record its kind -- see
72
+ // the lstat/stat bullet above -- after which these probes answer from that stat record
73
+ // too, since they consult the same getFsStatFamily.) realpathSync returns the real (symlink-resolved) path while the file is on
61
74
  // disk, and falls back to the LEXICALLY-resolved request path once it's bundle-only (a
62
75
  // symlink in a surviving ancestor dir is not re-resolved -- moot for the absent-config
63
76
  // case, but a canonicalize-then-compare under a symlinked ancestor could diverge between
@@ -392,11 +405,31 @@ export function installFsHooks({ async: patchAsync, getState, markAborted, isLoa
392
405
  return realReaddirSync(path, options)
393
406
  }
394
407
 
408
+ // Capture-side stat recording, shared by the sync/async lstat/stat wrappers: record
409
+ // the path's KIND (file vs directory) as a payload-free stat record (state.addFsStat),
410
+ // so the type getters -- lstatSync(x).isFile()/.isDirectory(), the common existence-
411
+ // and-kind check -- of a stat-ONLY path answer from the bundle at load. Only those two
412
+ // kinds are modelled (the serve shim's contract); a symlink (under lstat), socket,
413
+ // FIFO, or device records nothing. The caller has already received (or will receive)
414
+ // the REAL Stats -- recording never alters what the program sees. Guards mirror the
415
+ // byte readers: a path whose real location escapes the root (in-tree symlink pointing
416
+ // out) is not attested, a file whose bytes a write-mode sidecar already carries is
417
+ // skipped, and a recording conflict (a kind flip mid-run) taints the capture via
418
+ // markAborted so nothing inconsistent is written.
419
+ const captureStat = (state, abs, stats) => {
420
+ const isDir = stats.isDirectory()
421
+ if (!isDir && !stats.isFile()) return
422
+ const url = pathToFileURL(abs).toString()
423
+ if (!realContained(state.root, abs) || state.attestedBySidecar(url)) return
424
+ try { state.addFsStat(url, isDir ? 'directory' : 'file') } catch (err) { markAborted(err) }
425
+ }
426
+
395
427
  fs.lstatSync = function lstatSync(path, options) {
396
428
  const state = getState()
397
- // Serve-only, single-argument form. Capture mode is left to the real lstatSync
398
- // (the file is on disk, so its Stats is correct and complete) -- the lone exception
399
- // being a skipped source-map sidecar, reported absent in both modes.
429
+ // Single-argument form. Serve (bundle=load) the bundle-backed type getters for a
430
+ // recorded path; capture (bundle=add|replace) the observed kind via captureStat,
431
+ // handing the caller the REAL Stats (and real errors, e.g. ENOENT) untouched.
432
+ // A skipped source-map sidecar is reported absent in both modes.
400
433
  if (state && options == null) {
401
434
  const abs = toAbsPath(path)
402
435
  if (abs !== null && withinRoot(state.root, abs)) {
@@ -404,6 +437,13 @@ export function installFsHooks({ async: patchAsync, getState, markAborted, isLoa
404
437
  if (state.config.loadBundle) {
405
438
  const kind = state.getFsStatFamily(pathToFileURL(abs).toString())
406
439
  if (kind !== undefined) return bundleStats(realLstatSync, path, kind === 'directory')
440
+ } else if (state.config.writeBundle && !isLoadingModule()) {
441
+ // (Node's loader stats module paths through internal bindings, not this
442
+ // public API, but skip during a load window anyway, symmetric with
443
+ // readFileSync/readdirSync.)
444
+ const stats = realLstatSync(path)
445
+ captureStat(state, abs, stats)
446
+ return stats
407
447
  }
408
448
  }
409
449
  }
@@ -413,7 +453,10 @@ export function installFsHooks({ async: patchAsync, getState, markAborted, isLoa
413
453
  // statSync mirrors lstatSync exactly; the only difference is symlink following,
414
454
  // which is moot for a bundle-served path (there is no link to follow once the
415
455
  // bytes come from the bundle) but matters for the passthrough/present-on-disk
416
- // case, so it falls back to the real statSync rather than lstatSync.
456
+ // case AND for capture -- a statSync of an in-root symlink records the TARGET's
457
+ // kind (keyed at the requested path, like a byte read of it), while an lstatSync
458
+ // of it records nothing (a symlink isn't modelled) -- so each uses its own real
459
+ // implementation.
417
460
  fs.statSync = function statSync(path, options) {
418
461
  const state = getState()
419
462
  if (state && options == null) {
@@ -423,6 +466,10 @@ export function installFsHooks({ async: patchAsync, getState, markAborted, isLoa
423
466
  if (state.config.loadBundle) {
424
467
  const kind = state.getFsStatFamily(pathToFileURL(abs).toString())
425
468
  if (kind !== undefined) return bundleStats(realStatSync, path, kind === 'directory')
469
+ } else if (state.config.writeBundle && !isLoadingModule()) {
470
+ const stats = realStatSync(path)
471
+ captureStat(state, abs, stats)
472
+ return stats
426
473
  }
427
474
  }
428
475
  }
@@ -597,8 +644,10 @@ export function installFsHooks({ async: patchAsync, getState, markAborted, isLoa
597
644
  return realReaddirP(path, options)
598
645
  }
599
646
 
600
- // lstat/stat are serve-only (like their sync siblings); capture is left to the real
601
- // call. bundleStats's field fallback is synchronous, so it uses the sync real stat.
647
+ // lstat/stat capture and serve exactly like their sync siblings: serve the
648
+ // bundle-backed type getters, or record the real call's observed kind via
649
+ // captureStat while handing the caller the real Stats. bundleStats's field
650
+ // fallback is synchronous, so it uses the sync real stat.
602
651
  fs.lstat = function lstat(path, options, callback) {
603
652
  const cb = typeof options === 'function' ? options : callback
604
653
  // "single-argument" form: fn(path, cb) OR fn(path, null/undefined, cb). graceful-fs
@@ -610,6 +659,13 @@ export function installFsHooks({ async: patchAsync, getState, markAborted, isLoa
610
659
  if (t?.mode === 'serve') {
611
660
  const kind = t.state.getFsStatFamily(t.url)
612
661
  if (kind !== undefined) { queueMicrotask(() => cb(null, bundleStats(realLstatSync, path, kind === 'directory'))); return }
662
+ } else if (t?.mode === 'capture') {
663
+ realLstat(path, (err, stats) => {
664
+ if (err) return cb(err) // faithful error on the user's original path; nothing recorded
665
+ captureStat(t.state, t.abs, stats)
666
+ cb(null, stats)
667
+ })
668
+ return
613
669
  }
614
670
  return realLstat(path, options, callback)
615
671
  }
@@ -625,6 +681,13 @@ export function installFsHooks({ async: patchAsync, getState, markAborted, isLoa
625
681
  if (t?.mode === 'serve') {
626
682
  const kind = t.state.getFsStatFamily(t.url)
627
683
  if (kind !== undefined) { queueMicrotask(() => cb(null, bundleStats(realStatSync, path, kind === 'directory'))); return }
684
+ } else if (t?.mode === 'capture') {
685
+ realStat(path, (err, stats) => {
686
+ if (err) return cb(err)
687
+ captureStat(t.state, t.abs, stats)
688
+ cb(null, stats)
689
+ })
690
+ return
628
691
  }
629
692
  return realStat(path, options, callback)
630
693
  }
@@ -635,6 +698,10 @@ export function installFsHooks({ async: patchAsync, getState, markAborted, isLoa
635
698
  if (t?.mode === 'serve') {
636
699
  const kind = t.state.getFsStatFamily(t.url)
637
700
  if (kind !== undefined) return bundleStats(realLstatSync, path, kind === 'directory')
701
+ } else if (t?.mode === 'capture') {
702
+ const stats = await realLstatP(path)
703
+ captureStat(t.state, t.abs, stats)
704
+ return stats
638
705
  }
639
706
  return realLstatP(path, options)
640
707
  }
@@ -645,6 +712,10 @@ export function installFsHooks({ async: patchAsync, getState, markAborted, isLoa
645
712
  if (t?.mode === 'serve') {
646
713
  const kind = t.state.getFsStatFamily(t.url)
647
714
  if (kind !== undefined) return bundleStats(realStatSync, path, kind === 'directory')
715
+ } else if (t?.mode === 'capture') {
716
+ const stats = await realStatP(path)
717
+ captureStat(t.state, t.abs, stats)
718
+ return stats
648
719
  }
649
720
  return realStatP(path, options)
650
721
  }
package/src/hooks.js CHANGED
@@ -33,6 +33,7 @@ const NODEJS_FORMATS = new Set(['module', 'commonjs', 'json', 'module-typescript
33
33
  // the allowlist stays the single trust gate and the message is just UX.
34
34
  const NON_NODE_SOURCE_LANGUAGES = new Set(['solidity', 'php', 'bash', 'rust'])
35
35
  const RESOURCE_FORMATS = new Set(['resource', 'resource:base64'])
36
+ const STAT_FORMATS = new Set(['stat:file', 'stat:directory'])
36
37
  // The executable CommonJS formats (plain CJS + TS-CJS). Named like the sets above so
37
38
  // "which formats are CJS" lives in one place; the require-repair below keys off it.
38
39
  const CJS_FORMATS = new Set(['commonjs', 'commonjs-typescript'])
@@ -56,6 +57,13 @@ function refuseNonNodeFormat(format, url) {
56
57
  `fs.readdirSync result is not executable JavaScript. Read it with fs.readdirSync instead (${url})`
57
58
  )
58
59
  }
60
+ if (STAT_FORMATS.has(format)) {
61
+ throw new Error(
62
+ `[stasis] cannot import '${url}': the bundle carries only a payload-free stat record ` +
63
+ `('${format}', an fs.lstatSync/statSync capture attesting existence and kind) -- ` +
64
+ `not the file's content. Capture a run that reads or imports it to bundle its bytes.`
65
+ )
66
+ }
59
67
  // Unknown format string: usually a tampered or forward-incompatible bundle.
60
68
  throw new Error(
61
69
  `[stasis] cannot execute '${url}': attested format '${format}' is not a Node loader ` +
@@ -461,7 +469,10 @@ function initState(root) {
461
469
  // not taint, so the files captured so far ARE still written. That is intentional and
462
470
  // safe: those recorded hashes are accurate (nothing drifted is baked in), and a later
463
471
  // lock=frozen run fails closed on anything missing. Unhandled signals (SIGINT/SIGTERM
464
- // with no handler) bypass exit hooks entirely; servers own that behavior, we don't touch it.
472
+ // with no handler) bypass exit hooks entirely; servers own that behavior, we don't touch
473
+ // it -- except for a capturing CHILD under the EXODUS_STASIS_SHARD_SIGNAL_FLUSH opt-in
474
+ // (StasisMetro sets it for its force-killed transform workers), which flushes its shard
475
+ // on SIGTERM and re-delivers the signal -- see the handler registered below.
465
476
  //
466
477
  // save() runs on EVERY beforeExit/exit firing rather than latching after the first.
467
478
  // These handlers were registered at initState -- before any user code ran -- so they fire
@@ -513,6 +524,64 @@ function initState(root) {
513
524
 
514
525
  process.on('beforeExit', save)
515
526
  process.on('exit', save)
527
+
528
+ // config.shardSignalFlush (EXODUS_STASIS_SHARD_SIGNAL_FLUSH, opt-in; StasisMetro's
529
+ // capture wiring sets it for its build's children -- see the plugin's constructor):
530
+ // flush the shard when a capturing child is ended BY SIGNAL. Metro's transform workers
531
+ // are routinely killed that way: jest-worker's end() sends its END message, gives the
532
+ // worker 500ms to drain its event loop, then forceExit()s it -- SIGTERM, and SIGKILL
533
+ // another 500ms later -- and a worker whose loop doesn't drain in time (a watcher or
534
+ // ref'd timer some transformer left behind) dies by SIGTERM, which bypasses
535
+ // beforeExit/exit entirely. Everything ONLY that worker observed (its fork-target
536
+ // entry, jest-worker's processChild.js; babel.config.js + the preset/plugin graph
537
+ // loaded per transform) then silently vanished from the capture, surfacing only later
538
+ // at bundle=load as "file not attested in bundle" when the forked child's loader can't
539
+ // be served its own entry. The handler runs the same save() the exit hooks run (for a
540
+ // child: forward the shard unless the capture aborted) and re-delivers the signal;
541
+ // semantics are preserved:
542
+ // - the `once` listener is already removed when the handler runs, so when no user
543
+ // listener remains the OS default disposition is restored and the re-kill terminates
544
+ // the process BY that signal (the parent still observes code=null, signal=SIGTERM);
545
+ // the finally makes that re-delivery unconditional even if a future save() edit
546
+ // grows a throw path (today it cannot throw on the child branch);
547
+ // - when user code owns process lifetime we only flush and do NOT re-kill. "User code"
548
+ // is detected two ways, because a `once` listener that ran EARLIER in this same emit
549
+ // has already removed itself and is invisible to a post-emit listenerCount: listeners
550
+ // present at REGISTRATION time (a --require preload's graceful-shutdown hook -- those
551
+ // always precede this initState-time registration) are remembered in
552
+ // `userOwnedSigterm`, and listeners added later are still attached when the handler
553
+ // runs. A user handler that exits normally re-flushes via the exit hooks
554
+ // (lastShardWritten dedups); if a SECOND signal kills it instead, capture accrued
555
+ // after this one-shot flush is lost -- an accepted residual, fail-closed at verify.
556
+ // The conservative direction is deliberate: when in doubt, don't re-kill -- the
557
+ // worst case is jest-worker's own SIGKILL landing 500ms later;
558
+ // - signal listeners don't ref the event loop, so a cleanly-draining worker still
559
+ // exits (and writes) exactly as before.
560
+ // NOT a global default: a signal listener changes a process's default-kill disposition,
561
+ // which in arbitrary user children is the user's domain -- the Metro plugin opts in its
562
+ // KNOWN tool workers, where flush-then-redeliver is the right trade. Gated additionally
563
+ // to a CHILD (the root's signal behavior stays untouched -- servers own it) with shard
564
+ // forwarding on; a channel that was never minted (root mint failure cleared DIR+KEY) just
565
+ // makes the flush a no-op via writeChildShard's own guard. SIGTERM only -- it's what
566
+ // jest-worker's forceExit sends (Metro doesn't override killSignal). Best-effort
567
+ // residuals, all fail-closed at a later frozen/load run: the flush must fit inside
568
+ // forceExit's 500ms SIGTERM->SIGKILL window; SIGKILL and any OTHER signal (group
569
+ // SIGINT/SIGHUP, a killSignal override) are not covered; and a capturing child that
570
+ // is itself the process EVALUATING metro.config.js (a nested orchestration) snapshots
571
+ // its Config before the plugin sets the flag, so only its DESCENDANTS are covered --
572
+ // see the plugin's KNOWN LIMITATIONS bullet.
573
+ if (isChildProcess && shardForwardingEnabled() && state.config.shardSignalFlush) {
574
+ const userOwnedSigterm = process.listenerCount('SIGTERM') > 0
575
+ process.once('SIGTERM', () => {
576
+ try {
577
+ save()
578
+ } finally {
579
+ if (!userOwnedSigterm && process.listenerCount('SIGTERM') === 0) {
580
+ process.kill(process.pid, 'SIGTERM')
581
+ }
582
+ }
583
+ })
584
+ }
516
585
  }
517
586
 
518
587
  function load(url, context, nextLoad) {
@@ -778,8 +847,9 @@ function patchCjsResolution() {
778
847
  // path.resolve()d form, matching native's normalized cache-key contract). Falling
779
848
  // through to native would stat a file the bundle carries but disk (pruned /
780
849
  // never-shipped node_modules) may not -- MODULE_NOT_FOUND on a servable path.
781
- // getFsStat === 'file' (not mere presence) keeps a --fs-captured directory
782
- // LISTING from hijacking native directory->main/index resolution. This widens
850
+ // hasFsFileContent (byte content, not getFsStat's kind) keeps a --fs-captured
851
+ // directory LISTING -- and a payload-free 'stat:*' record, whose bytes the
852
+ // bundle can NOT serve -- from hijacking native disk resolution. This widens
783
853
  // parentless reachability to any attested in-scope file when disk lacks the path;
784
854
  // that is bounded by attestation and the load hook's gates (getFile +
785
855
  // NODEJS_FORMATS), which remain the load-bearing checks.
@@ -788,7 +858,7 @@ function patchCjsResolution() {
788
858
  // re-resolves through here, and the no-parent shape survives on >=24.18 too (the
789
859
  // deferred-resolution branch and createCJSNoSourceModuleWrap still take it).
790
860
  const url = pathToFileURL(request).toString()
791
- if ((state.config.full || state.inNodeModules(url)) && state.getFsStat(url) === 'file') {
861
+ if ((state.config.full || state.inNodeModules(url)) && state.hasFsFileContent(url)) {
792
862
  return resolvePath(request)
793
863
  }
794
864
  }
package/src/lockfile.js CHANGED
@@ -119,7 +119,13 @@ export class Lockfile {
119
119
  // tampered or forward-incompatible lockfile fails closed at the schema
120
120
  // boundary, with a message that names the offending value.
121
121
  assert(KNOWN_FORMATS.has(format), `unknown format '${format}' for ${file}`)
122
- formats.set(file, format)
122
+ // The project root's `directory` listing is keyed '.' -- lockfiles written
123
+ // before that normalization keyed it '' (see moduleFileKey), which never
124
+ // matches the '.' the hash absorb (join('.', '')) and lookups use. Normalize
125
+ // on parse; both keys appearing is a duplicate under the alias -- fail closed.
126
+ const key = file === '' ? '.' : file
127
+ assert(!formats.has(key), `duplicate format key '${key}'`)
128
+ formats.set(key, format)
123
129
  }
124
130
  }
125
131
 
package/src/state.js CHANGED
@@ -11,7 +11,7 @@ import { Bundle } from './bundle.js'
11
11
  import { Lockfile } from './lockfile.js'
12
12
  import { canonicalizePath, sha512integrity, readFileSyncMaybe, noupsert } from './state-util.js'
13
13
  import { brotliOptions } from './brotli.js'
14
- import { CODE_EXTENSIONS, classifyExtension, fileMapToObject, moduleFileKey, objectToMaps, sortPaths, splitNodeModulesPath } from './util.js'
14
+ import { CODE_EXTENSIONS, classifyExtension, fileMapToObject, isStatFormat, moduleFileKey, objectToMaps, sortPaths, splitNodeModulesPath } from './util.js'
15
15
  import corePackage from './package.cjs'
16
16
 
17
17
  // Object-destructure off the namespace rather than `import { ... } from 'node:fs'`:
@@ -20,7 +20,7 @@ import corePackage from './package.cjs'
20
20
  // module.syncBuiltinESMExports() to refresh node:fs's ESM wrapper for user code.
21
21
  // Direct ESM destructured imports are live bindings and would re-resolve to the
22
22
  // mocked names when state.write() fires on beforeExit.
23
- const { existsSync, mkdirSync, readdirSync, readFileSync, realpathSync, rmSync, writeFileSync } = fs
23
+ const { existsSync, mkdirSync, readdirSync, readFileSync, realpathSync, rmSync, statSync, writeFileSync } = fs
24
24
 
25
25
  const FILE_CONFIG = 'stasis.config.json'
26
26
  const FILE_LOCK = 'stasis.lock.json'
@@ -40,6 +40,31 @@ function readPackageJSON(pkgAbsolute) {
40
40
  // be unsound.
41
41
  const VERSION = corePackage.version
42
42
 
43
+ // Set `format` for `file` in a formats map, applying the weak-stat-record priority
44
+ // rule shared by the LIVE map writers (addFsStat, addImport -- addFile/addFsDir drop
45
+ // a stale stat record in place before their own set) and the lockfile merge
46
+ // (#mergedFormats): a payload-free 'stat:*' record (addFsStat) YIELDS to a real
47
+ // format for the same file and never displaces one. Both directions arise
48
+ // legitimately in one capture: an import may reveal the real format of a path that
49
+ // was first only stat'd, and -- the reverse -- a stat may land on a path addImport
50
+ // already format-attested at RESOLVE time with no byte record for addFsStat's
51
+ // content skip to key off (stasis-core's own preload-cached modules are exactly
52
+ // that shape: the resolve hook records 'module', the load hook never fires, and a
53
+ // bundler's enhanced-resolve then stats the file). Everything else keeps noupsert's
54
+ // conflict-is-fatal stance: two divergent REAL formats, or a stat kind flip
55
+ // (stat:file vs stat:directory).
56
+ function upsertFormat(map, file, format) {
57
+ const existing = map.get(file)
58
+ if (existing !== undefined && existing !== format) {
59
+ if (isStatFormat(existing) && !isStatFormat(format)) {
60
+ map.set(file, format)
61
+ return
62
+ }
63
+ if (isStatFormat(format) && !isStatFormat(existing)) return
64
+ }
65
+ noupsert(map, file, format)
66
+ }
67
+
43
68
  // TODO: stricter format validation
44
69
 
45
70
  // Process-wide registry of every live State, kept on globalThis (not a module-local
@@ -190,9 +215,10 @@ export class State {
190
215
  // Per-artifact "last serialized" caches: write() compares the freshly serialized
191
216
  // JSON text against the cached one for each output (lockfile / unified bundle /
192
217
  // split code / split resources) and skips both the brotli step and the writeFileSync
193
- // when they match. Brotli at quality 11 dominates write cost, and webpack/esbuild
194
- // watch-mode rebuilds call write() on every rebuild whether or not the captured
195
- // graph actually changed -- this cache makes those no-ops fast. Persistent across
218
+ // when they match. Brotli at the default quality (11, tunable via
219
+ // config.brotliQuality) dominates write cost, and webpack/esbuild watch-mode
220
+ // rebuilds call write() on every rebuild whether or not the captured graph
221
+ // actually changed -- this cache makes those no-ops fast. Persistent across
196
222
  // write() calls within one process; null on the first call.
197
223
  #lastLockData = null
198
224
  #lastUnifiedBundle = null
@@ -939,7 +965,12 @@ export class State {
939
965
  assert.ok(absolute)
940
966
  const file = relative(this.root, absolute)
941
967
  assert.ok(!file.startsWith('..'))
942
- return file
968
+ // The project root itself is keyed '.' -- never '' (path.relative's raw answer).
969
+ // Reached only by a `--fs` directory capture/lookup of the root; '.' is what
970
+ // join('.', rel === '') re-derives when the lockfile is absorbed at load, so
971
+ // recording/looking up under '' would desync write from read (the root listing
972
+ // was written under '' yet hashed under '.', failing getFile's integrity check).
973
+ return file === '' ? '.' : file
943
974
  }
944
975
 
945
976
  // A file reached under node_modules whose REAL path lies outside any
@@ -1120,6 +1151,14 @@ export class State {
1120
1151
  if (!asResource && Bundle.isResourceFormat(format)) {
1121
1152
  throw new Error(`addFile: format '${format}' requires resource: true`)
1122
1153
  }
1154
+ // A payload-free stat record is never a legal addFile format: addFile records
1155
+ // CONTENT (bytes + hash), and a content record tagged 'stat:*' would desync the
1156
+ // "stat records carry no payload" invariant every consumer relies on. The only
1157
+ // producer is addFsStat; a caller passing it here (e.g. a forged child shard
1158
+ // replayed by mergeShard) is refused at the recording site.
1159
+ if (isStatFormat(format)) {
1160
+ throw new Error(`addFile: format '${format}' is a payload-free stat record; use addFsStat`)
1161
+ }
1123
1162
  // A resource can't be an entry: entries name code loaded by Node (the module
1124
1163
  // graph's roots), and Bundle.parse / assertEntry validate them as code-shaped
1125
1164
  // paths. A resource entry would land in this.entries -> codeBundle.entries
@@ -1133,6 +1172,14 @@ export class State {
1133
1172
  // Canonicalize + bucket by the owning package (shared with addFsDir).
1134
1173
  const { absolute, file, dir, module, closestType } = this.#locateModule(url)
1135
1174
 
1175
+ // A payload-free stat record (addFsStat: the path was lstat/stat'd before it was
1176
+ // read or imported) is superseded by real content: drop it so the format
1177
+ // inference/noupsert below records this file's ACTUAL format instead of
1178
+ // conflicting with the weak 'stat:*' tag. The lockfile-baseline counterpart (a
1179
+ // prior capture attested the path stat-only, this run reads it) lives in the
1180
+ // flip-check relaxation below and #mergedFormats' upgrade rule.
1181
+ if (isStatFormat(this.formats.get(file))) this.formats.delete(file)
1182
+
1136
1183
  // A code file can NEVER be recorded as a resource. `resources` -- the only gate
1137
1184
  // that admits an asset payload -- rejects code extensions outright (see
1138
1185
  // parseResourcesOption), so a resource:true call for a code extension means a
@@ -1274,7 +1321,10 @@ export class State {
1274
1321
  // --lock=replace / --bundle=replace.)
1275
1322
  if (this.config.writeLockfile && this.#lockFormats !== null && format != null && inAttestedZone) {
1276
1323
  const attested = this.#lockFormats.get(file)
1277
- assert.ok(attested === undefined || attested === format,
1324
+ // A payload-free 'stat:*' baseline is not a flip: the prior capture attested only
1325
+ // the path's existence/kind, and this run observing real content UPGRADES the
1326
+ // record (#mergedFormats overwrites the stat record with the real format).
1327
+ assert.ok(attested === undefined || attested === format || isStatFormat(attested),
1278
1328
  `format flip for ${file}: lockfile attests '${attested}', observed '${format}' (bytes unchanged) -- re-run with --lock=replace to re-attest`)
1279
1329
  }
1280
1330
 
@@ -1342,6 +1392,10 @@ export class State {
1342
1392
  assert.ok(Array.isArray(names) && names.every((n) => typeof n === 'string'),
1343
1393
  'addFsDir requires an array of string names')
1344
1394
  const { file, dir, module } = this.#locateModule(url, { directory: true })
1395
+ // As in addFile: a payload-free stat record (the dir was lstat/stat'd before it
1396
+ // was readdir'd) is superseded by the real listing -- drop it before the format
1397
+ // noupsert below records 'directory'.
1398
+ if (isStatFormat(this.formats.get(file))) this.formats.delete(file)
1345
1399
  const content = JSON.stringify(names.toSorted())
1346
1400
  const format = 'directory'
1347
1401
  const integrity = sha512integrity(content)
@@ -1376,6 +1430,43 @@ export class State {
1376
1430
  noupsert(this.formats, file, format)
1377
1431
  }
1378
1432
 
1433
+ // Record an `fs.lstatSync(path)`/`fs.statSync(path)` capture (`stasis run --fs`,
1434
+ // capture side, single-arg form): a PAYLOAD-FREE stat record -- `formats[file] =
1435
+ // 'stat:file' | 'stat:directory'`, no bytes, no hash, no module-files entry --
1436
+ // attesting only that the path existed with that KIND. That is exactly what the
1437
+ // load-side type-getter shim needs (bundleStats sources isFile()/isDirectory()
1438
+ // from getFsStat), so a stat-ONLY path -- never read, readdir'd, or imported --
1439
+ // still answers `lstatSync(x).isDirectory()` (and, transitively, the
1440
+ // existsSync/accessSync/realpathSync probes, which consult getFsStatFamily) at
1441
+ // bundle=load once it's gone from disk.
1442
+ //
1443
+ // Skipped when the path already has a content record (bytes or a directory
1444
+ // listing, whether captured this run or seeded from the lockfile/bundle): that
1445
+ // record already answers getFsStat, and a weak stat record must never sit beside
1446
+ // it (check-then-read -- lstatSync before readFileSync -- is the common pattern).
1447
+ // A path with a REAL format but no content record -- addImport attests the format
1448
+ // of a resolve-hook target whose load hook never fires (a preload-cached module) --
1449
+ // is likewise left alone: upsertFormat drops the stat record, the real format
1450
+ // wins (a plain noupsert here aborted real captures: enhanced-resolve stat'ing
1451
+ // stasis-core's own src/util.js under --fs + a bundler plugin). The REVERSE order
1452
+ // (stat first, real format later) is handled by addFile/addFsDir dropping the
1453
+ // stale stat record in place, addImport's upsertFormat, and #mergedFormats'
1454
+ // upgrade rule. A kind flip WITHIN the surviving stat records (stat'd as a file,
1455
+ // later stat'd as a directory) still conflicts and taints the capture, exactly
1456
+ // like a mid-run byte conflict.
1457
+ addFsStat(url, kind) {
1458
+ assert.ok(kind === 'file' || kind === 'directory', `addFsStat: unsupported kind '${kind}'`)
1459
+ const file = this.#canonicalFile(url)
1460
+ if (this.hashes.has(file) || this.sources.has(file) || this.resources.has(file)) return
1461
+ upsertFormat(this.formats, file, `stat:${kind}`)
1462
+ // Forwarded to the root via shardSnapshot's #observed-filtered formats, like
1463
+ // every other capture; only a child's shardSnapshot reads it, skip otherwise --
1464
+ // and only when a stat record actually landed (upsertFormat yields to an
1465
+ // existing real format, and forwarding THAT would ship an entry mergeShard's
1466
+ // stat replay ignores).
1467
+ if (this.config.childProcess && isStatFormat(this.formats.get(file))) this.#observed.add(file)
1468
+ }
1469
+
1379
1470
  // Serve an `fs.readFileSync` from the bundle (`stasis run --fs`, bundle=load).
1380
1471
  // Returns the raw bytes as a Buffer, or undefined when the path was not captured
1381
1472
  // (the hook then falls back to a real disk read) or names a captured directory (a
@@ -1407,10 +1498,10 @@ export class State {
1407
1498
 
1408
1499
  // Every ancestor directory implied by the bundle's recorded file/resource/directory
1409
1500
  // keys. A recorded `node_modules/dep/index.js` implies `node_modules/dep` and
1410
- // `node_modules` (and the root, ''). Built once; load-mode immutable (see field).
1501
+ // `node_modules` (and the root, '.'). Built once; load-mode immutable (see field).
1411
1502
  #impliedDirs() {
1412
1503
  if (this.#impliedDirIndex) return this.#impliedDirIndex
1413
- const dirs = new Set([''])
1504
+ const dirs = new Set(['.'])
1414
1505
  const add = (key) => {
1415
1506
  let prefix = ''
1416
1507
  const parts = key.split('/')
@@ -1421,26 +1512,53 @@ export class State {
1421
1512
  }
1422
1513
  for (const key of this.sources.keys()) add(key)
1423
1514
  for (const key of this.resources.keys()) add(key)
1515
+ // Payload-free stat records prove existence too: a 'stat:file' at
1516
+ // node_modules/dep/index.js implies node_modules and node_modules/dep are
1517
+ // directories exactly like a content record would, and a 'stat:directory'
1518
+ // likewise implies its own ancestors (the recorded dir itself is answered
1519
+ // directly by getFsStat's format branch, not via this index).
1520
+ for (const [key, format] of this.formats) if (isStatFormat(format)) add(key)
1424
1521
  this.#impliedDirIndex = dirs
1425
1522
  return dirs
1426
1523
  }
1427
1524
 
1428
1525
  // Classify a captured path for the `fs.lstatSync(x)/statSync(x)` .isFile()/.isDirectory()
1429
1526
  // shim (`stasis run --fs`, bundle=load): 'directory' for a readdir capture, 'file' for
1430
- // a readFileSync capture, 'directory' for an ancestor directory implied by a recorded
1431
- // file (e.g. `node_modules` when the bundle carries `node_modules/dep/index.js`), or
1432
- // undefined when the path wasn't captured (the shim then falls back to a real on-disk
1433
- // lstatSync). A directory lives in this.resources too, so the 'directory' format is
1434
- // checked first; implied dirs are checked last so an explicit file/dir record wins.
1527
+ // a readFileSync capture, the recorded kind for a payload-free stat record
1528
+ // ('stat:file'/'stat:directory', an lstat/stat capture of a path never read),
1529
+ // 'directory' for an ancestor directory implied by a recorded file (e.g.
1530
+ // `node_modules` when the bundle carries `node_modules/dep/index.js`), or
1531
+ // undefined when the path wasn't captured (the shim then falls back to a real
1532
+ // on-disk lstatSync). A directory lives in this.resources too, so the 'directory'
1533
+ // format is checked first; content records are checked before stat records
1534
+ // (defensive -- addFsStat never records beside content) and implied dirs come
1535
+ // last so an explicit record always wins. NB: 'file' here means "recorded as a
1536
+ // file", NOT "the bundle can serve its bytes" -- callers needing the latter
1537
+ // (resolution shims, byte-serving skips) must use hasFsFileContent.
1435
1538
  getFsStat(url) {
1436
1539
  let file
1437
1540
  try { file = this.#canonicalFile(url) } catch { return undefined }
1438
- if (this.formats.get(file) === 'directory') return 'directory'
1541
+ const format = this.formats.get(file)
1542
+ if (format === 'directory') return 'directory'
1439
1543
  if (this.sources.has(file) || this.resources.has(file)) return 'file'
1544
+ if (format === 'stat:file') return 'file'
1545
+ if (format === 'stat:directory') return 'directory'
1440
1546
  if (this.#impliedDirs().has(file)) return 'directory'
1441
1547
  return undefined
1442
1548
  }
1443
1549
 
1550
+ // True when the bundle carries actual BYTE content for `url` as a file -- code or
1551
+ // a resource payload -- as opposed to a directory listing, a payload-free 'stat:*'
1552
+ // existence record, or nothing. The CJS-resolution shim (hooks.js) and the
1553
+ // sidecar capture-skip route "can the bundle serve this file's bytes?" through
1554
+ // this instead of getFsStat, which also answers 'file' for stat-only records.
1555
+ hasFsFileContent(url) {
1556
+ let file
1557
+ try { file = this.#canonicalFile(url) } catch { return false }
1558
+ if (this.formats.get(file) === 'directory') return false
1559
+ return this.sources.has(file) || this.resources.has(file)
1560
+ }
1561
+
1444
1562
  // --fs <-> bundler-plugin coordination. A StasisWebpack/StasisEsbuild/StasisMetro SIDECAR
1445
1563
  // (its own bundleFile) captures the bundler's MODULE GRAPH into its OWN bundle. But the
1446
1564
  // bundler also reads every module's source through node:fs (webpack's inputFileSystem is
@@ -1462,11 +1580,11 @@ export class State {
1462
1580
  // on purpose: a file only this State has stays subject to --fs's own dedup / byte-conflict
1463
1581
  // detection (addFsFile's noupsert); the skip applies solely to a file a *sidecar* carries.
1464
1582
  attestedBySidecar(url) {
1465
- // `=== 'file'` (not merely `!== undefined`): the skip targets a FILE a sidecar carries (the
1466
- // graph the bundler reads through node:fs). getFsStat also returns 'directory' for an implied
1467
- // ancestor of a carried file; matching that would over-skip. Inert today (a readFileSync of a
1468
- // directory throws EISDIR before this is consulted) but `=== 'file'` states the intent exactly.
1469
- for (const s of this.#sidecars) if (s.getFsStat(url) === 'file') return true
1583
+ // hasFsFileContent (not getFsStat): the skip targets a file whose BYTES a sidecar carries
1584
+ // (the graph the bundler reads through node:fs). getFsStat would also match a 'directory'
1585
+ // implied ancestor of a carried file, or a payload-free 'stat:*' record -- neither of which
1586
+ // carries bytes, so matching them would over-skip and leave a genuine read unattested.
1587
+ for (const s of this.#sidecars) if (s.hasFsFileContent(url)) return true
1470
1588
  return false
1471
1589
  }
1472
1590
 
@@ -1520,7 +1638,19 @@ export class State {
1520
1638
  if (format === 'resource:base64') source = Buffer.from(source, 'base64')
1521
1639
  } else {
1522
1640
  source = this.sources.get(file)
1523
- if (source === undefined) throw new Error(`stasis: file not attested in bundle: ${url}`)
1641
+ if (source === undefined) {
1642
+ // Name the stat-record case: the bundle DOES know this path, just not its bytes
1643
+ // (an fs.lstatSync/statSync capture attests existence/kind only), so "not
1644
+ // attested" would misdiagnose it. Loading it requires a capture that reads or
1645
+ // imports it.
1646
+ if (isStatFormat(format)) {
1647
+ throw new Error(
1648
+ `stasis: only a payload-free stat record ('${format}') is attested for ${url} -- ` +
1649
+ `the capture stat'd this path but never read or imported it, so the bundle has no bytes to serve`
1650
+ )
1651
+ }
1652
+ throw new Error(`stasis: file not attested in bundle: ${url}`)
1653
+ }
1524
1654
  }
1525
1655
  // Without a lockfile the bundle is self-attesting: hashes would be derived
1526
1656
  // from the same source bytes we'd then verify, which is a tautology.
@@ -1528,8 +1658,23 @@ export class State {
1528
1658
  return { source, format }
1529
1659
  }
1530
1660
 
1661
+ // The recorded LOADER format for a project-relative file, or undefined. Masks
1662
+ // payload-free stat records: 'stat:*' attests existence/kind for the --fs stat and
1663
+ // probe shims (getFsStat reads this.formats directly), NOT how bytes parse -- so
1664
+ // loader-format consumers must see "no recorded format". Without the mask, a
1665
+ // require.resolve()d target that was also stat'd (a resolve-only edge: attested
1666
+ // path, no bytes, exactly the supported require.resolve case) came back as format
1667
+ // 'stat:file' and the resolve hook's executable-format gate refused a perfectly
1668
+ // valid resolution -- and Node itself would choke on the format regardless.
1669
+ // getFile deliberately does NOT mask: it needs the stat tag to explain a byte-less
1670
+ // load, and bytes smuggled under a 'stat:*' tag must still hit the loader's gate.
1671
+ #loaderFormat(file) {
1672
+ const format = this.formats.get(file)
1673
+ return isStatFormat(format) ? undefined : format
1674
+ }
1675
+
1531
1676
  getFormat(url) {
1532
- return this.formats.get(this.#canonicalFile(url))
1677
+ return this.#loaderFormat(this.#canonicalFile(url))
1533
1678
  }
1534
1679
 
1535
1680
  // Different conditions / import attributes can yield different URLs/formats for the same parent+specifier
@@ -1612,7 +1757,11 @@ export class State {
1612
1757
  if (!imports.has(parent)) imports.set(parent, new Map())
1613
1758
  const specifiers = imports.get(parent)
1614
1759
  noupsert(specifiers, specifier, file)
1615
- if (format) noupsert(this.formats, file, format)
1760
+ // upsertFormat (not a bare noupsert): the resolve hook may attest the format of
1761
+ // a target the program already lstat/stat'd under --fs (a payload-free
1762
+ // 'stat:file' record) -- the real format replaces the weak stat record instead
1763
+ // of aborting the capture as a conflict.
1764
+ if (format) upsertFormat(this.formats, file, format)
1616
1765
  }
1617
1766
 
1618
1767
  getImport(parentURL, specifier, { conditions = '*', importAttributes } = {}) {
@@ -1643,7 +1792,7 @@ export class State {
1643
1792
  const abs = this.resolveBundled(parentURL, specifier)
1644
1793
  if (abs !== undefined) {
1645
1794
  const f = relative(this.root, abs)
1646
- return { url: pathToFileURL(abs).toString(), format: this.formats.get(f) }
1795
+ return { url: pathToFileURL(abs).toString(), format: this.#loaderFormat(f) }
1647
1796
  }
1648
1797
  }
1649
1798
  // Throw with Node's ERR_MODULE_NOT_FOUND shape rather than asserting:
@@ -1666,7 +1815,10 @@ export class State {
1666
1815
  throw err
1667
1816
  }
1668
1817
  const url = pathToFileURL(resolve(this.root, file)).toString()
1669
- const format = this.formats.get(file) // might be undefined e.g. for some bundlers
1818
+ // #loaderFormat: might be undefined (e.g. some bundlers record no format), and a
1819
+ // payload-free stat record is masked -- a resolve-only edge's target (recorded by
1820
+ // require.resolve, never loaded) may carry one, and it is not a loader format.
1821
+ const format = this.#loaderFormat(file)
1670
1822
  return { url, format }
1671
1823
  }
1672
1824
 
@@ -1732,12 +1884,19 @@ export class State {
1732
1884
  // Union of lockfile-attested and observed/bundle-served formats, same
1733
1885
  // append-only stance as #mergedImports: conflicting formats for one file are
1734
1886
  // fatal (noupsert). Sidecars' formats are unioned in for the same reason.
1887
+ // The one exception is a payload-free stat record ('stat:*', addFsStat): it is
1888
+ // WEAK by design -- real content observed for the same file (a lock=add re-run
1889
+ // READING a path a prior capture only stat'd, or a sidecar bundling a file this
1890
+ // run also stat'd) UPGRADES the record instead of conflicting, and a stat record
1891
+ // never displaces a real format (upsertFormat, the same rule the live-map
1892
+ // writers apply). Two REAL formats -- and two divergent stat kinds (stat:file
1893
+ // vs stat:directory) -- stay fatal.
1735
1894
  #mergedFormats() {
1736
1895
  const merged = new Map()
1737
1896
  if (this.#lockFormats) for (const [file, format] of this.#lockFormats) merged.set(file, format)
1738
- for (const [file, format] of this.formats) noupsert(merged, file, format)
1897
+ for (const [file, format] of this.formats) upsertFormat(merged, file, format)
1739
1898
  for (const sidecar of this.#sidecars) {
1740
- for (const [file, format] of sidecar.formats) noupsert(merged, file, format)
1899
+ for (const [file, format] of sidecar.formats) upsertFormat(merged, file, format)
1741
1900
  }
1742
1901
  return merged
1743
1902
  }
@@ -1824,6 +1983,28 @@ export class State {
1824
1983
  return consumers > 1 ? reason : undefined
1825
1984
  }
1826
1985
 
1986
+ // The formats map a bundle artifact declares. Normally `this.formats` as-is; the
1987
+ // one adjustment is dropping a payload-free stat record ('stat:*') that the run's
1988
+ // UNIFIED attestation upgraded to a real format -- a write-mode sidecar bundling a
1989
+ // file this run also stat'd (stat-before-plugin-capture ordering, so addFile's
1990
+ // in-place drop never saw it). The lockfile then attests the REAL format
1991
+ // (#mergedFormats' upgrade), and a bundle still declaring 'stat:*' for that file
1992
+ // would fail its lockfile cross-check at load (#mergeBundleMetadata). Cheap in the
1993
+ // common case: with no write-mode sidecars the live map is already consistent
1994
+ // (addFile/addFsDir drop superseded stat records in place) and is returned as-is.
1995
+ #formatsForBundle() {
1996
+ if (this.#sidecars.size === 0) return this.formats
1997
+ const merged = this.#mergedFormats()
1998
+ let out = null // copy-on-write: clone only when an entry must be dropped
1999
+ for (const [file, format] of this.formats) {
2000
+ if (isStatFormat(format) && merged.get(file) !== format) {
2001
+ if (out === null) out = new Map(this.formats)
2002
+ out.delete(file)
2003
+ }
2004
+ }
2005
+ return out ?? this.formats
2006
+ }
2007
+
1827
2008
  get sourceBundle() {
1828
2009
  // One bundle holds both code and resources; merge the two content maps (their key
1829
2010
  // sets are disjoint -- a file is either code or a resource) and let `formats` tag
@@ -1841,7 +2022,7 @@ export class State {
1841
2022
  config: this.config.values,
1842
2023
  entries: this.entries,
1843
2024
  modules: this.#bundleModules(contents),
1844
- formats: this.formats,
2025
+ formats: this.#formatsForBundle(),
1845
2026
  imports: this.imports,
1846
2027
  reason: this.#bundleReason(contents.keys()),
1847
2028
  })
@@ -1862,8 +2043,11 @@ export class State {
1862
2043
  // Resource files don't appear in `this.sources` (addFile routes by format), so
1863
2044
  // restricting #bundleModules to `this.sources` automatically yields the code-only
1864
2045
  // view. Formats and modules are filtered to drop resource-only dirs/files.
2046
+ // Payload-free stat records are NOT resource formats, so they ride the code half
2047
+ // (like the other content-less metadata, entries/imports) -- the resources half's
2048
+ // strict resource-formats-only shape check would reject them.
1865
2049
  const codeFormats = new Map()
1866
- for (const [file, format] of this.formats) {
2050
+ for (const [file, format] of this.#formatsForBundle()) {
1867
2051
  if (!Bundle.isResourceFormat(format)) codeFormats.set(file, format)
1868
2052
  }
1869
2053
  return new Bundle({
@@ -1914,7 +2098,14 @@ export class State {
1914
2098
  // worker child like worker-farm's, a .node addon). The resolution is real and
1915
2099
  // must be attested so the same require.resolve() returns the same path at
1916
2100
  // load; the file simply has no bytes -- require.resolve returns a path, load()
1917
- // never runs for it, so getFile is never asked to serve it.
2101
+ // never runs for it, so getFile is never asked to serve it. Bytes are attested
2102
+ // only by whoever actually LOADS the file: a fork/worker target (jest-worker's
2103
+ // processChild) is loaded in the forked CHILD as its entry, and that child's
2104
+ // own capture contributes them via the --child-process shard -- flushed even on
2105
+ // SIGTERM under the Metro plugin's opt-in (hooks.js), so a force-killed
2106
+ // transform worker still reports. Deliberately NOT seeded here from the parent:
2107
+ // attesting bytes this process never loaded would widen the trust set to
2108
+ // everything that merely resolves.
1918
2109
  // Guards:
1919
2110
  // - skip out-of-scope targets (mirroring #collectMissingImportedFiles) so a
1920
2111
  // node_modules-scope artifact doesn't attest workspace resolutions it isn't
@@ -2145,6 +2336,47 @@ export class State {
2145
2336
  }
2146
2337
  }
2147
2338
  }
2339
+ // Payload-free stat records (`--fs` lstat/stat captures) live ONLY in the shard's
2340
+ // formats map -- no module-files entry -- so the modules loop above never visits
2341
+ // them. Replay each by re-deriving the kind from DISK (the same disk-is-truth
2342
+ // stance as the byte/listing re-reads: a shard can't inject a forged kind), via
2343
+ // addFsStat so a path the root already attests with content is skipped, exactly
2344
+ // as if this process had stat'd it. Range-check the path BEFORE touching disk,
2345
+ // like the directory branch above; a path gone from disk (or of an unmodelled
2346
+ // kind, e.g. a socket) is skipped, best-effort like every other replay.
2347
+ if (lf.formats) {
2348
+ let realRoot // resolved once, on the first record: the containment anchor below
2349
+ for (const [file, format] of lf.formats) {
2350
+ if (!isStatFormat(format)) continue
2351
+ const absolute = resolve(this.root, file)
2352
+ const relFromRoot = relative(this.root, absolute)
2353
+ if (relFromRoot.startsWith('..') || isAbsolute(relFromRoot)) continue
2354
+ try {
2355
+ // statSync (follow symlinks), NOT lstatSync: the child's capture followed them
2356
+ // -- a statSync of an in-root symlink records the TARGET's kind keyed at the
2357
+ // requested path (pnpm's public node_modules/<pkg> links are exactly this
2358
+ // shape), and an lstat of a symlink was never recorded at all -- so for every
2359
+ // key a legitimate shard can carry, statSync reproduces the recorded kind
2360
+ // while lstatSync would report the link itself and silently drop the record.
2361
+ const stats = statSync(absolute)
2362
+ const kind = stats.isDirectory() ? 'directory' : stats.isFile() ? 'file' : null
2363
+ if (kind === null) continue
2364
+ // Because statSync follows links, re-assert the capture side's containment
2365
+ // (fs.js captureStat's realContained) before attesting: the REAL location must
2366
+ // stay inside the root's real path, so a shard entry keyed at an in-root
2367
+ // symlink that points OUT of the tree is skipped, never recorded.
2368
+ if (realRoot === undefined) {
2369
+ try { realRoot = realpathSync(this.root) } catch { realRoot = this.root }
2370
+ }
2371
+ const relReal = relative(realRoot, realpathSync(absolute))
2372
+ if (relReal !== '' && (relReal.startsWith('..') || isAbsolute(relReal))) continue
2373
+ this.addFsStat(pathToFileURL(absolute).toString(), kind)
2374
+ } catch {
2375
+ // Gone from disk (or a dangling link), or rejected (kind conflict with the
2376
+ // root's own capture): skip -- the root's capture stays intact.
2377
+ }
2378
+ }
2379
+ }
2148
2380
  if (lf.imports) {
2149
2381
  for (const [conditions, byParent] of lf.imports) {
2150
2382
  // Reverse #conditionsKey: '*' stays '*'; otherwise the key is a ', '-joined condition
@@ -2193,7 +2425,7 @@ export class State {
2193
2425
  const text = serialize()
2194
2426
  if (text !== lastText) {
2195
2427
  mkdirSync(dirname(path), { recursive: true })
2196
- writeFileSync(path, brotliCompressSync(text, brotliOptions()))
2428
+ writeFileSync(path, brotliCompressSync(text, brotliOptions(this.config.brotliQuality)))
2197
2429
  return text
2198
2430
  }
2199
2431
  return lastText
package/src/util.js CHANGED
@@ -19,7 +19,11 @@ const sep = '/'
19
19
  // Source languages (analysis-only, not runnable by Node) — solidity, php, bash, rust
20
20
  // Resources (asset payloads) — resource (raw UTF-8), resource:base64 (binary)
21
21
  // Filesystem captures (`stasis run --fs`) — directory (a JSON-serialized,
22
- // sorted `fs.readdirSync` listing; a resource-like raw-UTF-8 payload)
22
+ // sorted `fs.readdirSync` listing; a resource-like raw-UTF-8 payload), and the
23
+ // payload-free stat records stat:file / stat:directory (an `fs.lstatSync`/
24
+ // `fs.statSync` capture: attests only that the path existed with that KIND —
25
+ // no bytes, no hash, no module-files entry — so isFile()/isDirectory() answer
26
+ // from the bundle at load; see isStatFormat below)
23
27
  // Adding a new format is a deliberate schema change: list it here AND extend
24
28
  // hooks.js's executable allowlist if Node should serve it from a bundle.
25
29
  export const KNOWN_FORMATS = new Set([
@@ -35,6 +39,8 @@ export const KNOWN_FORMATS = new Set([
35
39
  'resource',
36
40
  'resource:base64',
37
41
  'directory',
42
+ 'stat:file',
43
+ 'stat:directory',
38
44
  ])
39
45
 
40
46
  // File extensions whose bytes are JS-shaped code -- Node's loader and the
@@ -50,6 +56,14 @@ export const KNOWN_FORMATS = new Set([
50
56
  // own set, so an fs-read tagged a `.jsx` 'resource' while the import tagged it code.
51
57
  export const CODE_EXTENSIONS = new Set(['js', 'mjs', 'cjs', 'ts', 'jsx', 'tsx', 'json', 'mts', 'cts'])
52
58
 
59
+ // The payload-free stat-record formats (`stasis run --fs` lstatSync/statSync captures).
60
+ // A stat record attests a path's KIND (file vs directory) without any content, so it
61
+ // lives ONLY in the `formats` maps — never in a module's hashed `files`, never as a
62
+ // bundle payload. It is deliberately WEAK: real content recorded for the same path (a
63
+ // read, a readdir listing, an import) supersedes it — see State's addFile/addFsDir
64
+ // stale-record drop and #mergedFormats' upgrade rule.
65
+ export const isStatFormat = (format) => format === 'stat:file' || format === 'stat:directory'
66
+
53
67
  // Lowercased, dot-less extension of a path, or '' if none.
54
68
  export function pathExt(filePath) {
55
69
  const m = /\.([^./\\]+)$/.exec(filePath)
@@ -87,6 +101,20 @@ export function parseResourcesOption(label, resources) {
87
101
  return out
88
102
  }
89
103
 
104
+ export const isBrotliQuality = (n) => Number.isInteger(n) && n >= 0 && n <= 11
105
+
106
+ // Parse an EXODUS_STASIS_BROTLI_QUALITY / --brotli-quality string into a brotli quality
107
+ // (integer 0..11). `${n}` must round-trip back to the input, so Number()-coercible
108
+ // non-canonical forms ('5.0', '05', ' 5 ', whitespace -> 0) throw instead of silently
109
+ // selecting an unintended quality. The single parser for the env var and both CLIs.
110
+ export function parseBrotliQuality(name, value) {
111
+ const n = Number(value)
112
+ if (`${n}` !== value || !isBrotliQuality(n)) {
113
+ throw new RangeError(`${name} must be an integer 0..11 (got '${value}')`)
114
+ }
115
+ return n
116
+ }
117
+
90
118
  // Classifies a file against the code set + a parsed resources allowlist. Returns 'code'
91
119
  // (track with its loader format), 'resource' (track with a 'resource'/'resource:base64'
92
120
  // format -- the encoding is chosen from content), or 'unknown' (caller must reject). A
@@ -116,12 +144,14 @@ export function extSetsEqual(a, b) {
116
144
  // the bucketing State/Bundle apply. The `rel === ''` branch is reached only by a
117
145
  // `directory` capture whose path IS a module root (e.g. `fs.readdirSync` of a
118
146
  // package dir, or of the project root): the listing is keyed at the bucket itself,
119
- // so the flat key is the dir (or '' for the workspace root) — never `${dir}/`,
120
- // which a trailing-slash join would wrongly produce and break the round-trip. For
121
- // every ordinary file `rel` is a real basename, so this matches the historical
147
+ // so the flat key is the dir — never `${dir}/`, which a trailing-slash join would
148
+ // wrongly produce and break the round-trip. The workspace root keys at '.' (the
149
+ // '.' bucket's own dir), NOT '': join('.', '') === '.' is what lockfile re-absorb
150
+ // derives, so a '' key would be written but never found again on load. For every
151
+ // ordinary file `rel` is a real basename, so this matches the historical
122
152
  // `dir === '.' ? rel : `${dir}/${rel}`` exactly.
123
153
  export function moduleFileKey(dir, rel) {
124
- if (rel === '') return dir === '.' ? '' : dir
154
+ if (rel === '') return dir
125
155
  return dir === '.' ? rel : `${dir}/${rel}`
126
156
  }
127
157