@exodus/stasis-core 1.0.0-beta.0 → 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/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
@@ -444,71 +470,8 @@ export class State {
444
470
  : lockProbe
445
471
  const lockPath = explicitLockPath || join(rootDir, FILE_LOCK)
446
472
 
447
- if (lock && !this.config.useLockfile && !this.config.ignoreLockfile) {
448
- throw new Error(`Unexpected ${lockPath} with config.lock = 'none'`)
449
- }
450
- if (sources && !this.config.writeBundle && !this.config.loadBundle && !this.config.ignoreBundle && !this.config.frozenBundle) {
451
- throw new Error(`Unexpected ${sourcesPath} with config.bundle = 'none'`)
452
- }
453
-
454
- // A frozen bundle is self-attesting -- it verifies disk against the bundle's
455
- // own bytes, so (unlike load/add) it needs no sibling lockfile and is exempt
456
- // from this "a lockfile is required before a bundle's sources can be trusted"
457
- // guard. This is what lets bundle=frozen compose with lock=add (bootstrapping a
458
- // fresh lockfile from the verified run) without a pre-existing lockfile.
459
- if (sources && !lock && this.config.useLockfile && !this.config.replaceLockfile && !this.config.frozenBundle) {
460
- throw new Error('stasis.lock.json missing, can not use sources')
461
- }
462
-
463
- if (lock && this.config.useLockfile && !this.config.replaceLockfile) {
464
- const lockfile = Lockfile.parse(lock)
465
- if (this.config.frozen) assert.equal(lockfile.config.scope, this.config.scope)
466
-
467
- const includeSources = lockfile.config.scope === 'full' && this.config.full
468
- for (const [dir, info] of lockfile.modules) {
469
- if (!dir.includes('node_modules') && !includeSources) continue
470
- this.modules.set(dir, info)
471
- }
472
- if (includeSources) this.entries = lockfile.entries
473
-
474
- for (const [dir, { files }] of this.modules) {
475
- for (const [name, hash] of Object.entries(files)) {
476
- noupsert(this.hashes, join(dir, name), hash)
477
- }
478
- }
479
- this.#lockImports = lockfile.imports
480
- this.#lockFormats = lockfile.formats
481
- // Frozen promises verification, but a lockfile predating resolution
482
- // or format attestation can only vouch for bytes -- those metadata
483
- // (from a bundle OR observed on disk) go unchecked until it's
484
- // regenerated.
485
- if (this.config.frozen && this.#lockImports === null) {
486
- console.warn('[stasis] Warning: lockfile does not attest resolutions; they are trusted as-is. Regenerate the lockfile to enable this check.')
487
- }
488
- if (this.config.frozen && this.#lockFormats === null) {
489
- console.warn('[stasis] Warning: lockfile does not attest formats; they are trusted as-is. Regenerate the lockfile to enable this check.')
490
- }
491
- lockfileLoaded = true
492
- this.#lockfileLoaded = true
493
- }
494
-
495
- if (sources && (this.config.writeBundle || this.config.loadBundle || this.config.frozenBundle) && !this.config.replaceBundle) {
496
- this.#absorbCodeBundle(sources, sourcesPath, lockfileLoaded)
497
- }
498
-
499
- // Split-bundle layout: when `resourcesBundleFile` is configured, resources
500
- // live in a separate file. Load it as a standalone Bundle (entries empty,
501
- // imports empty, formats restricted to resource tags) and union into the
502
- // state already absorbed from `bundleFile`. The strict-shape asserts catch
503
- // a writer that accidentally leaked code into the resources file or a
504
- // tampered file claiming entries/imports it shouldn't have.
505
- if (this.config.resourcesBundleFile) {
506
- const resourcesPath = this.config.resourcesBundleFile
507
- const resourcesData = readFileSyncMaybe(dirname(resourcesPath), basename(resourcesPath))
508
- if (resourcesData && (this.config.writeBundle || this.config.loadBundle || this.config.frozenBundle) && !this.config.replaceBundle) {
509
- this.#absorbResourcesBundle(resourcesData, { lockfileLoaded, resourcesPath })
510
- }
511
- }
473
+ lockfileLoaded = this.#absorbLockfile(lock, lockPath)
474
+ this.#loadBundleArtifacts(sources, sourcesPath, lockfileLoaded)
512
475
 
513
476
  // The innermost matching rootDir is authoritative (per-dir opt-in, see above), so stop
514
477
  // scanning once committed. An explicit/config `bundleFile` is rootDir-independent: without
@@ -522,67 +485,33 @@ export class State {
522
485
  // Explicit lockfile path with no other discovery indicator at any rootDir: the
523
486
  // discovery loop never set `loaded`, so the lockfile branch above never ran. Process
524
487
  // the explicit lockfile here against the already-resolved `this.root` (outermost
525
- // package.json) so the run still has its attestation. Inlines the same gates as the
526
- // in-loop branch -- a future refactor could merge the two by extracting a helper.
488
+ // package.json) so the run still has its attestation.
527
489
  if (!loaded && explicitLockPath) {
528
490
  const lock = readFileSyncMaybe(dirname(explicitLockPath), basename(explicitLockPath), 'utf-8')
529
- if (lock && !this.config.useLockfile && !this.config.ignoreLockfile) {
530
- throw new Error(`Unexpected ${explicitLockPath} with config.lock = 'none'`)
531
- }
532
- if (lock && this.config.useLockfile && !this.config.replaceLockfile) {
533
- const lockfile = Lockfile.parse(lock)
534
- if (this.config.frozen) assert.equal(lockfile.config.scope, this.config.scope)
535
- const includeSources = lockfile.config.scope === 'full' && this.config.full
536
- for (const [dir, info] of lockfile.modules) {
537
- if (!dir.includes('node_modules') && !includeSources) continue
538
- this.modules.set(dir, info)
539
- }
540
- if (includeSources) this.entries = lockfile.entries
541
- for (const [dir, { files }] of this.modules) {
542
- for (const [name, hash] of Object.entries(files)) {
543
- noupsert(this.hashes, join(dir, name), hash)
544
- }
545
- }
546
- this.#lockImports = lockfile.imports
547
- this.#lockFormats = lockfile.formats
548
- if (this.config.frozen && this.#lockImports === null) {
549
- console.warn('[stasis] Warning: lockfile does not attest resolutions; they are trusted as-is. Regenerate the lockfile to enable this check.')
550
- }
551
- if (this.config.frozen && this.#lockFormats === null) {
552
- console.warn('[stasis] Warning: lockfile does not attest formats; they are trusted as-is. Regenerate the lockfile to enable this check.')
553
- }
554
- lockfileLoaded = true
555
- this.#lockfileLoaded = true
556
- }
557
- }
558
-
559
- // Explicit (flag/env) bundleFile with no rootDir-dependent indicator at any rootDir: like the
560
- // explicit lockfile above, it was suppressed as a root-detection signal so it couldn't pull the
561
- // root down to the innermost package, so the loop never loaded it. Load it here against
562
- // `this.root` (the outermost package.json) -- the same root capture commits to when no signal
563
- // exists -- so its capture-root-relative keys line up with how they're looked up. Inlines the
564
- // same gates as the in-loop bundle branch.
565
- if (!loaded && explicitBundlePath) {
566
- const sourcesPath = this.config.bundleFile
567
- const sources = readFileSyncMaybe(dirname(sourcesPath), basename(sourcesPath))
568
- if (sources && !this.config.writeBundle && !this.config.loadBundle && !this.config.ignoreBundle && !this.config.frozenBundle) {
569
- throw new Error(`Unexpected ${sourcesPath} with config.bundle = 'none'`)
570
- }
571
- if (sources && !lockfileLoaded && this.config.useLockfile && !this.config.replaceLockfile && !this.config.frozenBundle) {
572
- throw new Error('stasis.lock.json missing, can not use sources')
573
- }
574
- if (sources && (this.config.writeBundle || this.config.loadBundle || this.config.frozenBundle) && !this.config.replaceBundle) {
575
- this.#absorbCodeBundle(sources, sourcesPath, lockfileLoaded)
576
- }
577
- // Split-bundle resources: same post-loop treatment (resourcesBundleFile is likewise an
578
- // explicit, rootDir-independent path). Mirrors the in-loop resources branch.
579
- if (this.config.resourcesBundleFile) {
580
- const resourcesPath = this.config.resourcesBundleFile
581
- const resourcesData = readFileSyncMaybe(dirname(resourcesPath), basename(resourcesPath))
582
- if (resourcesData && (this.config.writeBundle || this.config.loadBundle || this.config.frozenBundle) && !this.config.replaceBundle) {
583
- this.#absorbResourcesBundle(resourcesData, { lockfileLoaded, resourcesPath })
584
- }
585
- }
491
+ lockfileLoaded = this.#absorbLockfile(lock, explicitLockPath)
492
+ }
493
+
494
+ // Explicit (flag/env) bundleFile and/or resourcesBundleFile with no rootDir-dependent
495
+ // indicator at any rootDir: like the explicit lockfile above, an explicit bundleFile was
496
+ // suppressed as a root-detection signal so it couldn't pull the root down to the innermost
497
+ // package, so the loop never loaded it. Load it here against `this.root` (the outermost
498
+ // package.json) -- the same root capture commits to when no signal exists -- so its
499
+ // capture-root-relative keys line up with how they're looked up. `resourcesBundleFile` is in
500
+ // the gate for the resources-only split shape (#absorbResourcesBundle documents it as legal):
501
+ // with no code bundle on disk there is no other reason to reach the loader here, yet the
502
+ // explicit resources half must still be absorbed. Post-loop, both paths are necessarily
503
+ // flag/env: a stasis.config.json could only have set them by also committing the loop.
504
+ //
505
+ // NB: the outermost root depends on where the upward walk stopped (PROJECT_CWD, .git,
506
+ // pnpm-workspace.yaml -- see potentialRoots above). Capture and load must agree on that
507
+ // boundary for the keys to line up: e.g. a capture under yarn (PROJECT_CWD set to an inner
508
+ // workspace dir) and a bare load of the same bundle (walks up to the repo's .git) commit
509
+ // different roots and fail with "outside the project root" / "not attested".
510
+ if (!loaded && (explicitBundlePath || this.config.resourcesBundleFile)) {
511
+ const sources = explicitBundlePath
512
+ ? readFileSyncMaybe(dirname(explicitBundlePath), basename(explicitBundlePath))
513
+ : null
514
+ this.#loadBundleArtifacts(sources, explicitBundlePath, lockfileLoaded)
586
515
  }
587
516
 
588
517
  // Frozen modes must have actually loaded their attestation. Asserting here --
@@ -624,6 +553,87 @@ export class State {
624
553
  liveStates().add(this)
625
554
  }
626
555
 
556
+ // Absorb a lockfile's attestation into this State: the run-scope module/hash maps, the
557
+ // imports/formats attestation, and the frozen-mode warnings for lockfiles predating those
558
+ // attestations. Shared by the discovery loop (a committed rootDir) and the post-loop fallback
559
+ // for an explicit `config.lockFile` -- a rootDir-independent path, so it is suppressed as a
560
+ // root-detection signal and loaded at the outermost root instead. Returns whether the lockfile
561
+ // was actually absorbed (the caller's `lockfileLoaded`).
562
+ #absorbLockfile(lock, lockPath) {
563
+ if (lock && !this.config.useLockfile && !this.config.ignoreLockfile) {
564
+ throw new Error(`Unexpected ${lockPath} with config.lock = 'none'`)
565
+ }
566
+ if (!lock || !this.config.useLockfile || this.config.replaceLockfile) return false
567
+ const lockfile = Lockfile.parse(lock)
568
+ if (this.config.frozen) assert.equal(lockfile.config.scope, this.config.scope)
569
+
570
+ const includeSources = lockfile.config.scope === 'full' && this.config.full
571
+ for (const [dir, info] of lockfile.modules) {
572
+ if (!dir.includes('node_modules') && !includeSources) continue
573
+ this.modules.set(dir, info)
574
+ }
575
+ if (includeSources) this.entries = lockfile.entries
576
+
577
+ for (const [dir, { files }] of this.modules) {
578
+ for (const [name, hash] of Object.entries(files)) {
579
+ noupsert(this.hashes, join(dir, name), hash)
580
+ }
581
+ }
582
+ this.#lockImports = lockfile.imports
583
+ this.#lockFormats = lockfile.formats
584
+ // Frozen promises verification, but a lockfile predating resolution
585
+ // or format attestation can only vouch for bytes -- those metadata
586
+ // (from a bundle OR observed on disk) go unchecked until it's
587
+ // regenerated.
588
+ if (this.config.frozen && this.#lockImports === null) {
589
+ console.warn('[stasis] Warning: lockfile does not attest resolutions; they are trusted as-is. Regenerate the lockfile to enable this check.')
590
+ }
591
+ if (this.config.frozen && this.#lockFormats === null) {
592
+ console.warn('[stasis] Warning: lockfile does not attest formats; they are trusted as-is. Regenerate the lockfile to enable this check.')
593
+ }
594
+ this.#lockfileLoaded = true
595
+ return true
596
+ }
597
+
598
+ // Gate and load the bundle artifacts for an already-committed root: the unified
599
+ // code[+resource] bundle read from `sourcesPath`, plus the split `resourcesBundleFile` when
600
+ // one is configured. Shared by the discovery loop and the post-loop explicit-path fallback so
601
+ // the mode guards cannot drift between the two. `sources` may be null -- no bundle on disk, or
602
+ // a resources-only deployment -- in which case only the resources half applies.
603
+ //
604
+ // The missing-lockfile guard tests `lockfileLoaded` where the pre-extraction in-loop code
605
+ // tested raw lockfile presence; equivalent at this call point, since whenever the guard can
606
+ // fire (useLockfile && !replaceLockfile) #absorbLockfile absorbed the lockfile iff it existed.
607
+ #loadBundleArtifacts(sources, sourcesPath, lockfileLoaded) {
608
+ if (sources && !this.config.writeBundle && !this.config.loadBundle && !this.config.ignoreBundle && !this.config.frozenBundle) {
609
+ throw new Error(`Unexpected ${sourcesPath} with config.bundle = 'none'`)
610
+ }
611
+ // A frozen bundle is self-attesting -- it verifies disk against the bundle's
612
+ // own bytes, so (unlike load/add) it needs no sibling lockfile and is exempt
613
+ // from this "a lockfile is required before a bundle's sources can be trusted"
614
+ // guard. This is what lets bundle=frozen compose with lock=add (bootstrapping a
615
+ // fresh lockfile from the verified run) without a pre-existing lockfile.
616
+ if (sources && !lockfileLoaded && this.config.useLockfile && !this.config.replaceLockfile && !this.config.frozenBundle) {
617
+ throw new Error('stasis.lock.json missing, can not use sources')
618
+ }
619
+ if (sources && (this.config.writeBundle || this.config.loadBundle || this.config.frozenBundle) && !this.config.replaceBundle) {
620
+ this.#absorbCodeBundle(sources, sourcesPath, lockfileLoaded)
621
+ }
622
+ // Split-bundle layout: when `resourcesBundleFile` is configured, resources
623
+ // live in a separate file. Load it as a standalone Bundle (entries empty,
624
+ // imports empty, formats restricted to resource tags) and union into the
625
+ // state already absorbed from `bundleFile`. The strict-shape asserts catch
626
+ // a writer that accidentally leaked code into the resources file or a
627
+ // tampered file claiming entries/imports it shouldn't have.
628
+ if (this.config.resourcesBundleFile) {
629
+ const resourcesPath = this.config.resourcesBundleFile
630
+ const resourcesData = readFileSyncMaybe(dirname(resourcesPath), basename(resourcesPath))
631
+ if (resourcesData && (this.config.writeBundle || this.config.loadBundle || this.config.frozenBundle) && !this.config.replaceBundle) {
632
+ this.#absorbResourcesBundle(resourcesData, { lockfileLoaded, resourcesPath })
633
+ }
634
+ }
635
+ }
636
+
627
637
  // Absorb a unified code+resource bundle's metadata and payloads into this State. Shared by the
628
638
  // discovery loop (a committed rootDir carrying a stasis signal) and the post-loop fallback that
629
639
  // loads an explicit (rootDir-independent) bundleFile against the outermost root.
@@ -955,7 +965,12 @@ export class State {
955
965
  assert.ok(absolute)
956
966
  const file = relative(this.root, absolute)
957
967
  assert.ok(!file.startsWith('..'))
958
- 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
959
974
  }
960
975
 
961
976
  // A file reached under node_modules whose REAL path lies outside any
@@ -1136,6 +1151,14 @@ export class State {
1136
1151
  if (!asResource && Bundle.isResourceFormat(format)) {
1137
1152
  throw new Error(`addFile: format '${format}' requires resource: true`)
1138
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
+ }
1139
1162
  // A resource can't be an entry: entries name code loaded by Node (the module
1140
1163
  // graph's roots), and Bundle.parse / assertEntry validate them as code-shaped
1141
1164
  // paths. A resource entry would land in this.entries -> codeBundle.entries
@@ -1149,6 +1172,14 @@ export class State {
1149
1172
  // Canonicalize + bucket by the owning package (shared with addFsDir).
1150
1173
  const { absolute, file, dir, module, closestType } = this.#locateModule(url)
1151
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
+
1152
1183
  // A code file can NEVER be recorded as a resource. `resources` -- the only gate
1153
1184
  // that admits an asset payload -- rejects code extensions outright (see
1154
1185
  // parseResourcesOption), so a resource:true call for a code extension means a
@@ -1290,7 +1321,10 @@ export class State {
1290
1321
  // --lock=replace / --bundle=replace.)
1291
1322
  if (this.config.writeLockfile && this.#lockFormats !== null && format != null && inAttestedZone) {
1292
1323
  const attested = this.#lockFormats.get(file)
1293
- 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),
1294
1328
  `format flip for ${file}: lockfile attests '${attested}', observed '${format}' (bytes unchanged) -- re-run with --lock=replace to re-attest`)
1295
1329
  }
1296
1330
 
@@ -1358,6 +1392,10 @@ export class State {
1358
1392
  assert.ok(Array.isArray(names) && names.every((n) => typeof n === 'string'),
1359
1393
  'addFsDir requires an array of string names')
1360
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)
1361
1399
  const content = JSON.stringify(names.toSorted())
1362
1400
  const format = 'directory'
1363
1401
  const integrity = sha512integrity(content)
@@ -1392,6 +1430,43 @@ export class State {
1392
1430
  noupsert(this.formats, file, format)
1393
1431
  }
1394
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
+
1395
1470
  // Serve an `fs.readFileSync` from the bundle (`stasis run --fs`, bundle=load).
1396
1471
  // Returns the raw bytes as a Buffer, or undefined when the path was not captured
1397
1472
  // (the hook then falls back to a real disk read) or names a captured directory (a
@@ -1423,10 +1498,10 @@ export class State {
1423
1498
 
1424
1499
  // Every ancestor directory implied by the bundle's recorded file/resource/directory
1425
1500
  // keys. A recorded `node_modules/dep/index.js` implies `node_modules/dep` and
1426
- // `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).
1427
1502
  #impliedDirs() {
1428
1503
  if (this.#impliedDirIndex) return this.#impliedDirIndex
1429
- const dirs = new Set([''])
1504
+ const dirs = new Set(['.'])
1430
1505
  const add = (key) => {
1431
1506
  let prefix = ''
1432
1507
  const parts = key.split('/')
@@ -1437,26 +1512,53 @@ export class State {
1437
1512
  }
1438
1513
  for (const key of this.sources.keys()) add(key)
1439
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)
1440
1521
  this.#impliedDirIndex = dirs
1441
1522
  return dirs
1442
1523
  }
1443
1524
 
1444
1525
  // Classify a captured path for the `fs.lstatSync(x)/statSync(x)` .isFile()/.isDirectory()
1445
1526
  // shim (`stasis run --fs`, bundle=load): 'directory' for a readdir capture, 'file' for
1446
- // a readFileSync capture, 'directory' for an ancestor directory implied by a recorded
1447
- // file (e.g. `node_modules` when the bundle carries `node_modules/dep/index.js`), or
1448
- // undefined when the path wasn't captured (the shim then falls back to a real on-disk
1449
- // lstatSync). A directory lives in this.resources too, so the 'directory' format is
1450
- // 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.
1451
1538
  getFsStat(url) {
1452
1539
  let file
1453
1540
  try { file = this.#canonicalFile(url) } catch { return undefined }
1454
- if (this.formats.get(file) === 'directory') return 'directory'
1541
+ const format = this.formats.get(file)
1542
+ if (format === 'directory') return 'directory'
1455
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'
1456
1546
  if (this.#impliedDirs().has(file)) return 'directory'
1457
1547
  return undefined
1458
1548
  }
1459
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
+
1460
1562
  // --fs <-> bundler-plugin coordination. A StasisWebpack/StasisEsbuild/StasisMetro SIDECAR
1461
1563
  // (its own bundleFile) captures the bundler's MODULE GRAPH into its OWN bundle. But the
1462
1564
  // bundler also reads every module's source through node:fs (webpack's inputFileSystem is
@@ -1478,11 +1580,11 @@ export class State {
1478
1580
  // on purpose: a file only this State has stays subject to --fs's own dedup / byte-conflict
1479
1581
  // detection (addFsFile's noupsert); the skip applies solely to a file a *sidecar* carries.
1480
1582
  attestedBySidecar(url) {
1481
- // `=== 'file'` (not merely `!== undefined`): the skip targets a FILE a sidecar carries (the
1482
- // graph the bundler reads through node:fs). getFsStat also returns 'directory' for an implied
1483
- // ancestor of a carried file; matching that would over-skip. Inert today (a readFileSync of a
1484
- // directory throws EISDIR before this is consulted) but `=== 'file'` states the intent exactly.
1485
- 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
1486
1588
  return false
1487
1589
  }
1488
1590
 
@@ -1536,7 +1638,19 @@ export class State {
1536
1638
  if (format === 'resource:base64') source = Buffer.from(source, 'base64')
1537
1639
  } else {
1538
1640
  source = this.sources.get(file)
1539
- 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
+ }
1540
1654
  }
1541
1655
  // Without a lockfile the bundle is self-attesting: hashes would be derived
1542
1656
  // from the same source bytes we'd then verify, which is a tautology.
@@ -1544,8 +1658,23 @@ export class State {
1544
1658
  return { source, format }
1545
1659
  }
1546
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
+
1547
1676
  getFormat(url) {
1548
- return this.formats.get(this.#canonicalFile(url))
1677
+ return this.#loaderFormat(this.#canonicalFile(url))
1549
1678
  }
1550
1679
 
1551
1680
  // Different conditions / import attributes can yield different URLs/formats for the same parent+specifier
@@ -1628,7 +1757,11 @@ export class State {
1628
1757
  if (!imports.has(parent)) imports.set(parent, new Map())
1629
1758
  const specifiers = imports.get(parent)
1630
1759
  noupsert(specifiers, specifier, file)
1631
- 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)
1632
1765
  }
1633
1766
 
1634
1767
  getImport(parentURL, specifier, { conditions = '*', importAttributes } = {}) {
@@ -1659,7 +1792,7 @@ export class State {
1659
1792
  const abs = this.resolveBundled(parentURL, specifier)
1660
1793
  if (abs !== undefined) {
1661
1794
  const f = relative(this.root, abs)
1662
- return { url: pathToFileURL(abs).toString(), format: this.formats.get(f) }
1795
+ return { url: pathToFileURL(abs).toString(), format: this.#loaderFormat(f) }
1663
1796
  }
1664
1797
  }
1665
1798
  // Throw with Node's ERR_MODULE_NOT_FOUND shape rather than asserting:
@@ -1682,7 +1815,10 @@ export class State {
1682
1815
  throw err
1683
1816
  }
1684
1817
  const url = pathToFileURL(resolve(this.root, file)).toString()
1685
- 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)
1686
1822
  return { url, format }
1687
1823
  }
1688
1824
 
@@ -1748,12 +1884,19 @@ export class State {
1748
1884
  // Union of lockfile-attested and observed/bundle-served formats, same
1749
1885
  // append-only stance as #mergedImports: conflicting formats for one file are
1750
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.
1751
1894
  #mergedFormats() {
1752
1895
  const merged = new Map()
1753
1896
  if (this.#lockFormats) for (const [file, format] of this.#lockFormats) merged.set(file, format)
1754
- for (const [file, format] of this.formats) noupsert(merged, file, format)
1897
+ for (const [file, format] of this.formats) upsertFormat(merged, file, format)
1755
1898
  for (const sidecar of this.#sidecars) {
1756
- for (const [file, format] of sidecar.formats) noupsert(merged, file, format)
1899
+ for (const [file, format] of sidecar.formats) upsertFormat(merged, file, format)
1757
1900
  }
1758
1901
  return merged
1759
1902
  }
@@ -1840,6 +1983,28 @@ export class State {
1840
1983
  return consumers > 1 ? reason : undefined
1841
1984
  }
1842
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
+
1843
2008
  get sourceBundle() {
1844
2009
  // One bundle holds both code and resources; merge the two content maps (their key
1845
2010
  // sets are disjoint -- a file is either code or a resource) and let `formats` tag
@@ -1857,7 +2022,7 @@ export class State {
1857
2022
  config: this.config.values,
1858
2023
  entries: this.entries,
1859
2024
  modules: this.#bundleModules(contents),
1860
- formats: this.formats,
2025
+ formats: this.#formatsForBundle(),
1861
2026
  imports: this.imports,
1862
2027
  reason: this.#bundleReason(contents.keys()),
1863
2028
  })
@@ -1878,8 +2043,11 @@ export class State {
1878
2043
  // Resource files don't appear in `this.sources` (addFile routes by format), so
1879
2044
  // restricting #bundleModules to `this.sources` automatically yields the code-only
1880
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.
1881
2049
  const codeFormats = new Map()
1882
- for (const [file, format] of this.formats) {
2050
+ for (const [file, format] of this.#formatsForBundle()) {
1883
2051
  if (!Bundle.isResourceFormat(format)) codeFormats.set(file, format)
1884
2052
  }
1885
2053
  return new Bundle({
@@ -1930,7 +2098,14 @@ export class State {
1930
2098
  // worker child like worker-farm's, a .node addon). The resolution is real and
1931
2099
  // must be attested so the same require.resolve() returns the same path at
1932
2100
  // load; the file simply has no bytes -- require.resolve returns a path, load()
1933
- // 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.
1934
2109
  // Guards:
1935
2110
  // - skip out-of-scope targets (mirroring #collectMissingImportedFiles) so a
1936
2111
  // node_modules-scope artifact doesn't attest workspace resolutions it isn't
@@ -2161,6 +2336,47 @@ export class State {
2161
2336
  }
2162
2337
  }
2163
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
+ }
2164
2380
  if (lf.imports) {
2165
2381
  for (const [conditions, byParent] of lf.imports) {
2166
2382
  // Reverse #conditionsKey: '*' stays '*'; otherwise the key is a ', '-joined condition
@@ -2209,7 +2425,7 @@ export class State {
2209
2425
  const text = serialize()
2210
2426
  if (text !== lastText) {
2211
2427
  mkdirSync(dirname(path), { recursive: true })
2212
- writeFileSync(path, brotliCompressSync(text, brotliOptions()))
2428
+ writeFileSync(path, brotliCompressSync(text, brotliOptions(this.config.brotliQuality)))
2213
2429
  return text
2214
2430
  }
2215
2431
  return lastText