@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.
- package/bin/stasis-core.js +17 -3
- package/package.json +1 -1
- package/src/brotli.js +17 -10
- package/src/bundle.js +7 -1
- package/src/config.js +53 -4
- package/src/fs.js +86 -15
- package/src/hooks.js +74 -4
- package/src/lockfile.js +7 -1
- package/src/state.js +263 -31
- package/src/util.js +35 -5
package/bin/stasis-core.js
CHANGED
|
@@ -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
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.
|
|
7
|
-
//
|
|
8
|
-
//
|
|
9
|
-
// pays the default cost
|
|
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 (
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
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
|
-
|
|
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
|
|
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:
|
|
35
|
-
//
|
|
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.
|
|
41
|
-
//
|
|
42
|
-
//
|
|
43
|
-
//
|
|
44
|
-
//
|
|
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.
|
|
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
|
-
//
|
|
398
|
-
//
|
|
399
|
-
//
|
|
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
|
|
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
|
|
601
|
-
//
|
|
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
|
|
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
|
-
//
|
|
782
|
-
// LISTING
|
|
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.
|
|
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
|
-
|
|
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
|
|
194
|
-
//
|
|
195
|
-
//
|
|
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
|
-
|
|
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
|
-
|
|
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,
|
|
1431
|
-
// file
|
|
1432
|
-
//
|
|
1433
|
-
//
|
|
1434
|
-
//
|
|
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
|
-
|
|
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
|
-
//
|
|
1466
|
-
// graph the bundler reads through node:fs). getFsStat also
|
|
1467
|
-
// ancestor of a carried file
|
|
1468
|
-
//
|
|
1469
|
-
for (const s of this.#sidecars) if (s.
|
|
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)
|
|
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
|
|
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
|
-
|
|
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
|
|
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
|
-
|
|
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)
|
|
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)
|
|
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
|
|
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
|
|
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
|
|
120
|
-
//
|
|
121
|
-
//
|
|
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
|
|
154
|
+
if (rel === '') return dir
|
|
125
155
|
return dir === '.' ? rel : `${dir}/${rel}`
|
|
126
156
|
}
|
|
127
157
|
|