@exodus/stasis-core 1.0.0-beta.0
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/LICENSE +21 -0
- package/README.md +9 -0
- package/bin/stasis-core.js +116 -0
- package/package.json +50 -0
- package/src/brotli.js +21 -0
- package/src/bundle.js +256 -0
- package/src/config.js +426 -0
- package/src/fs.js +712 -0
- package/src/hooks.js +826 -0
- package/src/loader.js +6 -0
- package/src/lockfile.js +152 -0
- package/src/package.cjs +1 -0
- package/src/prune.js +532 -0
- package/src/state-util.js +64 -0
- package/src/state.js +2375 -0
- package/src/util.js +210 -0
package/src/state.js
ADDED
|
@@ -0,0 +1,2375 @@
|
|
|
1
|
+
import assert from 'node:assert/strict'
|
|
2
|
+
import { isUtf8 } from 'node:buffer'
|
|
3
|
+
import * as fs from 'node:fs'
|
|
4
|
+
import { join, resolve, relative, basename, dirname, extname, isAbsolute } from 'node:path'
|
|
5
|
+
import { fileURLToPath, pathToFileURL } from 'node:url'
|
|
6
|
+
import { findPackageJSON } from 'node:module'
|
|
7
|
+
import { brotliCompressSync, brotliDecompressSync } from 'node:zlib'
|
|
8
|
+
|
|
9
|
+
import { Config } from './config.js'
|
|
10
|
+
import { Bundle } from './bundle.js'
|
|
11
|
+
import { Lockfile } from './lockfile.js'
|
|
12
|
+
import { canonicalizePath, sha512integrity, readFileSyncMaybe, noupsert } from './state-util.js'
|
|
13
|
+
import { brotliOptions } from './brotli.js'
|
|
14
|
+
import { CODE_EXTENSIONS, classifyExtension, fileMapToObject, moduleFileKey, objectToMaps, sortPaths, splitNodeModulesPath } from './util.js'
|
|
15
|
+
import corePackage from './package.cjs'
|
|
16
|
+
|
|
17
|
+
// Object-destructure off the namespace rather than `import { ... } from 'node:fs'`:
|
|
18
|
+
// the destructured `const` captures function values at this module's eval time, so
|
|
19
|
+
// stasis keeps writing through the real fs even after --mock (loaded after us) calls
|
|
20
|
+
// module.syncBuiltinESMExports() to refresh node:fs's ESM wrapper for user code.
|
|
21
|
+
// Direct ESM destructured imports are live bindings and would re-resolve to the
|
|
22
|
+
// mocked names when state.write() fires on beforeExit.
|
|
23
|
+
const { existsSync, mkdirSync, readdirSync, readFileSync, realpathSync, rmSync, writeFileSync } = fs
|
|
24
|
+
|
|
25
|
+
const FILE_CONFIG = 'stasis.config.json'
|
|
26
|
+
const FILE_LOCK = 'stasis.lock.json'
|
|
27
|
+
const FILE_CODE = 'stasis.code.br'
|
|
28
|
+
|
|
29
|
+
function readPackageJSON(pkgAbsolute) {
|
|
30
|
+
const buf = readFileSync(pkgAbsolute)
|
|
31
|
+
assert.ok(isUtf8(buf))
|
|
32
|
+
return JSON.parse(buf.toString())
|
|
33
|
+
}
|
|
34
|
+
|
|
35
|
+
// This stasis-core copy's own version, via src/package.cjs (a CommonJS re-export of
|
|
36
|
+
// package.json -- bundler-safe, unlike a runtime fs read or `import ... with`). A child
|
|
37
|
+
// (sidecar) State must EXACTLY match its parent's version (enforced in the constructor's
|
|
38
|
+
// parent branch): a sidecar shares the parent's maps by reference and reads its private
|
|
39
|
+
// fields, so a version skew between two @exodus/stasis-core copies in one process would
|
|
40
|
+
// be unsound.
|
|
41
|
+
const VERSION = corePackage.version
|
|
42
|
+
|
|
43
|
+
// TODO: stricter format validation
|
|
44
|
+
|
|
45
|
+
// Process-wide registry of every live State, kept on globalThis (not a module-local
|
|
46
|
+
// variable) so it is shared across DUPLICATE stasis-core copies in one process -- e.g. a
|
|
47
|
+
// stasis bundle that carries its own stasis-core alongside the outer loader's. A
|
|
48
|
+
// cross-realm `Symbol.for` key makes every state.js copy reach the same Set. Two roles:
|
|
49
|
+
// - the preload (top-level) State is the unique member flagged isPreload, found by
|
|
50
|
+
// State.preload; constructing a second preload (from ANY copy) is rejected, so the
|
|
51
|
+
// "one top-level state" invariant holds process-wide; and
|
|
52
|
+
// - write-target collision detection (#claimWritePath) scans every member's claimed
|
|
53
|
+
// paths, so no two live States write the same lockfile/bundle/resourcesBundle path --
|
|
54
|
+
// across copies, AND whether or not a preload exists.
|
|
55
|
+
const STATES_KEY = Symbol.for('@exodus/stasis-core/states')
|
|
56
|
+
function liveStates() {
|
|
57
|
+
return (globalThis[STATES_KEY] ??= new Set())
|
|
58
|
+
}
|
|
59
|
+
|
|
60
|
+
export class State {
|
|
61
|
+
hashes = new Map()
|
|
62
|
+
entries = new Set()
|
|
63
|
+
sources = new Map()
|
|
64
|
+
resources = new Map()
|
|
65
|
+
formats = new Map()
|
|
66
|
+
modules = new Map()
|
|
67
|
+
imports = new Map()
|
|
68
|
+
config
|
|
69
|
+
root
|
|
70
|
+
#parent
|
|
71
|
+
|
|
72
|
+
// True iff this is THE preload (top-level) State. Exposed via `get isPreload()` so
|
|
73
|
+
// State.preload can find the unique flagged member of the global registry across copies.
|
|
74
|
+
#isPreload = false
|
|
75
|
+
|
|
76
|
+
// This State's claimed write-target paths (canonicalized -> label), for cross-State
|
|
77
|
+
// collision detection. Exposed via `claimedWritePathLabel()` so the global scan in
|
|
78
|
+
// #claimWritePath can consult States from other stasis-core copies.
|
|
79
|
+
#claims = new Map()
|
|
80
|
+
|
|
81
|
+
// For a parent: WRITE-mode sidecar States constructed against it -- the lockfile
|
|
82
|
+
// CONTRIBUTORS. The unified lockfile (built by the parent's lockData via
|
|
83
|
+
// #mergedImports/#mergedFormats) must union the parent's own imports / formats with
|
|
84
|
+
// every sidecar's, otherwise resolution edges and format attestations a sidecar
|
|
85
|
+
// bundler-plugin observed (sidecar.addImport / addFile populate sidecar-local
|
|
86
|
+
// this.imports/this.formats) would never reach the lockfile. Hashes / entries /
|
|
87
|
+
// modules are already shared by reference; this closes the same gap for imports and
|
|
88
|
+
// formats. Also the set attestedBySidecar consults, so --fs skips re-capturing a
|
|
89
|
+
// read the bundler plugin already records here. Unused on sidecars themselves.
|
|
90
|
+
#sidecars = new Set()
|
|
91
|
+
|
|
92
|
+
// For a parent: LOAD-mode sidecar States -- read-only family members, NOT lockfile
|
|
93
|
+
// contributors. A bundler plugin's load-mode sidecar carries the module graph in its
|
|
94
|
+
// bundle; getFs*Family consults this set so a --fs read at load of a graph file the
|
|
95
|
+
// sidecar carries is served from it (the symmetric counterpart to the #sidecars
|
|
96
|
+
// capture-skip). Kept separate from #sidecars precisely so these never enter
|
|
97
|
+
// #mergedImports/#mergedFormats -- a load-mode sidecar contributes no resolution edges
|
|
98
|
+
// or formats (the lockfile's trust-bearing content) to the unified lockfile (the boundary
|
|
99
|
+
// the writeBundle gate on registration enforces; see the constructor and registerReadSidecar).
|
|
100
|
+
#readSidecars = new Set()
|
|
101
|
+
|
|
102
|
+
// Resolutions attested by the loaded lockfile (conditions -> parent ->
|
|
103
|
+
// specifier -> file), or null when no lockfile was loaded / it predates
|
|
104
|
+
// resolution attestation. Kept separate from this.imports (the live
|
|
105
|
+
// observed/bundle-served map): the lockfile may attest a superset of what a
|
|
106
|
+
// given run observes or a given bundle carries.
|
|
107
|
+
#lockImports = null
|
|
108
|
+
|
|
109
|
+
// Loader formats attested by the loaded lockfile (file -> format), or null
|
|
110
|
+
// when none was loaded / it predates format attestation. Like #lockImports,
|
|
111
|
+
// kept apart from this.formats (the live observed/bundle-served map).
|
|
112
|
+
#lockFormats = null
|
|
113
|
+
|
|
114
|
+
// True iff this State (or, for a sidecar, its parent) loaded a lockfile from
|
|
115
|
+
// disk during construction. Drives #mergeBundleMetadata's cross-check-vs-absorb
|
|
116
|
+
// branch: with a lockfile, the bundle's metadata must agree with the lockfile's
|
|
117
|
+
// attestations; without one, the bundle's metadata is absorbed as the source of
|
|
118
|
+
// truth. Sidecars inherit this from the parent at construction time so a sidecar
|
|
119
|
+
// bundle is cross-checked against the parent's lockfile attestation rather than
|
|
120
|
+
// silently trusted.
|
|
121
|
+
#lockfileLoaded = false
|
|
122
|
+
|
|
123
|
+
// Project-relative keys of files/directories THIS process recorded via addFile/addFsDir this
|
|
124
|
+
// run (as opposed to the lockfile baseline seeded at construction). shardSnapshot() forwards
|
|
125
|
+
// only these, so a forked child's shard carries what it observed -- not a re-ship of the whole
|
|
126
|
+
// seeded lockfile.
|
|
127
|
+
#observed = new Set()
|
|
128
|
+
// file -> set of consumers that recorded it, for the bundle's informational `reason` field.
|
|
129
|
+
// Keyed by consumer ('run' for the loader/CLI; a plugin label like 'StasisMetro' for a plugin
|
|
130
|
+
// sharing this State). Populated only when bundling. See #recordReason / #bundleReason.
|
|
131
|
+
#reasonFiles = new Map()
|
|
132
|
+
// Supporting state so the bundle `reason` map's "run" entry stays accurate (see #bundleReason):
|
|
133
|
+
// files run loaded as a MODULE (#runImported), files run merely fs-READ after a plugin attached
|
|
134
|
+
// (#fsReadPostPlugin), and whether a bundler plugin has attached to this State (#pluginAttached).
|
|
135
|
+
#runImported = new Set()
|
|
136
|
+
#fsReadPostPlugin = new Set()
|
|
137
|
+
#pluginAttached = false
|
|
138
|
+
|
|
139
|
+
// Files, resolutions, and formats attested by a frozen bundle (bundle=frozen),
|
|
140
|
+
// or null when no frozen bundle was loaded. A frozen bundle plays the same
|
|
141
|
+
// read-only attestation role a frozen lockfile does, but anchored in the
|
|
142
|
+
// bundle's own bytes -- so bundle=frozen needs no sibling lockfile. The byte
|
|
143
|
+
// check itself is the noupsert of observed disk content into this.sources/
|
|
144
|
+
// this.resources (both pre-seeded from the bundle); these sets/maps close the
|
|
145
|
+
// attested set so a file, resolution, or format the bundle never recorded is
|
|
146
|
+
// rejected. Kept separate from the live this.sources/this.imports/this.formats,
|
|
147
|
+
// which addFile/addImport mutate.
|
|
148
|
+
#bundleSources = null
|
|
149
|
+
#bundleResources = null
|
|
150
|
+
#bundleImports = null
|
|
151
|
+
#bundleFormats = null
|
|
152
|
+
|
|
153
|
+
// Lazily-built set of directory paths IMPLIED by the bundle's recorded entries
|
|
154
|
+
// (files, resources, directory listings): a recorded `node_modules/dep/index.js`
|
|
155
|
+
// proves `node_modules` and `node_modules/dep` exist as directories even though
|
|
156
|
+
// neither was readdir'd. getFsStat consults it so
|
|
157
|
+
// `fs.statSync('node_modules').isDirectory()` succeeds at bundle=load. Built once
|
|
158
|
+
// in load mode, where this.imports / this.sources are immutable after construction.
|
|
159
|
+
#impliedDirIndex = null
|
|
160
|
+
|
|
161
|
+
// Capture-time native resolutions (parent URL -> specifier -> resolved URL)
|
|
162
|
+
// observed via the Module._resolveFilename shim: require.resolve() and any CJS
|
|
163
|
+
// require() that bypasses the resolve hook. write()'s backfill records the edges
|
|
164
|
+
// the hook missed (deduped, in-bundle targets only). Populated only during capture.
|
|
165
|
+
#observedResolutions = new Map()
|
|
166
|
+
|
|
167
|
+
// Node's require-condition set (e.g. ['require', 'node', 'node-addons',
|
|
168
|
+
// 'module-sync'], plus any --conditions), captured the first time addImport sees a
|
|
169
|
+
// require()-context edge. require()/require.resolve() resolve under THESE conditions
|
|
170
|
+
// -- they honor the `require` branch of conditional `exports`, so they're not
|
|
171
|
+
// condition-free -- so #backfillObservedResolutions keys the native
|
|
172
|
+
// (Module._resolveFilename) edges it recovers under this set rather than the
|
|
173
|
+
// wildcard '*'. That matches what the resolve hook records directly (newer Node) and
|
|
174
|
+
// unifies them with the require() bucket, so any capture that does at least one
|
|
175
|
+
// require() (the common case) yields the same lockfile on every Node version. null
|
|
176
|
+
// until observed -- a capture that ONLY require.resolve()s and never require()s
|
|
177
|
+
// leaves it null and backfill falls back to '*' (as before this change), which the
|
|
178
|
+
// getImport/resolveBundled wildcard fallbacks still match.
|
|
179
|
+
#requireConditions = null
|
|
180
|
+
|
|
181
|
+
// Absolute path of a package whose source files were loaded by Node BEFORE
|
|
182
|
+
// our hooks registered (the preload-cached set). Set by the loader's
|
|
183
|
+
// initState to stasis-core's own root; sidecars inherit it from their
|
|
184
|
+
// parent so plugin-driven write()s also backfill internal edges. write()'s
|
|
185
|
+
// backfill statically parses each file under this root and addImports its
|
|
186
|
+
// relative-specifier edges -- recovering the (state.js -> config.js)-shape
|
|
187
|
+
// edges that the live resolve hook never observed.
|
|
188
|
+
#preloadRoot = null
|
|
189
|
+
|
|
190
|
+
// Per-artifact "last serialized" caches: write() compares the freshly serialized
|
|
191
|
+
// JSON text against the cached one for each output (lockfile / unified bundle /
|
|
192
|
+
// 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
|
|
196
|
+
// write() calls within one process; null on the first call.
|
|
197
|
+
#lastLockData = null
|
|
198
|
+
#lastUnifiedBundle = null
|
|
199
|
+
#lastCodeBundle = null
|
|
200
|
+
#lastResourcesBundle = null
|
|
201
|
+
|
|
202
|
+
// Options:
|
|
203
|
+
// preload (boolean) -- register as the unique preload State (exposed via State.preload).
|
|
204
|
+
// Only one preload may exist at a time. The stasis loader is the only real caller.
|
|
205
|
+
// parent (State) -- run as a sidecar of this parent. Sidecar shares the parent's
|
|
206
|
+
// hashes/entries/modules (so addFile updates the unified lockfile through them) but
|
|
207
|
+
// manages its own sources/formats/imports/resources and emits its own bundle file.
|
|
208
|
+
// write() on a sidecar skips the lockfile (parent owns it) and only writes its bundle.
|
|
209
|
+
// All other keys forward to Config.
|
|
210
|
+
constructor(root, options = {}) {
|
|
211
|
+
// skipDiscovery: build a caller-populated, in-memory State with NO filesystem discovery -- root is the passed `root` arg, and sources/imports/formats/entries are filled in by the caller after construction (no package.json walk, no on-disk config/lockfile/bundle reads). For artifact-driven tooling like `stasis build`, which serves a parsed bundle (or a lockfile reconstructed + verified in memory) and must not depend on a project's stasis.config.json or read a stray stasis.code.br. Read-only (load/ignore) modes only.
|
|
212
|
+
const { preload: isPreload = false, parent: parentState, preloadRoot, skipDiscovery = false, ...configOptions } = options
|
|
213
|
+
this.config = new Config(configOptions)
|
|
214
|
+
if (isPreload) assert.ok(!State.preload, 'Only one preload Stasis instance is supported')
|
|
215
|
+
assert.ok(!(isPreload && parentState), 'preload and parent are mutually exclusive')
|
|
216
|
+
this.#isPreload = isPreload
|
|
217
|
+
|
|
218
|
+
if (parentState) {
|
|
219
|
+
// A child (sidecar) shares the parent's maps by reference and inherits its lockfile
|
|
220
|
+
// attestation, so the parent MUST be the exact same stasis-core VERSION -- but it
|
|
221
|
+
// need NOT be the same module copy. A bundle that carries its OWN stasis-core (e.g.
|
|
222
|
+
// a webpack script + StasisWebpack run under `stasis run --bundle=load`) has the
|
|
223
|
+
// plugin's copy coordinate with the OUTER loader's preload across the class brand.
|
|
224
|
+
// The exact-version match makes that sound; everything the sidecar reads from the
|
|
225
|
+
// parent goes through the parent's PUBLIC surface (`version`, `sidecarInheritance`,
|
|
226
|
+
// `registerSidecar`, and the shared public maps), never a private field a foreign
|
|
227
|
+
// class brand would deny. A version skew is unsound -- reject it with a clear error.
|
|
228
|
+
assert.equal(parentState.version, VERSION,
|
|
229
|
+
`child State version '${VERSION}' must exactly match parent version '${parentState.version}'`)
|
|
230
|
+
// Sidecar mode: short-circuit the on-disk discovery path. Lockfile data is shared by
|
|
231
|
+
// reference with the parent; only the sidecar's bundleFile (if any) is parsed here.
|
|
232
|
+
this.#parent = parentState
|
|
233
|
+
this.root = parentState.root
|
|
234
|
+
this.hashes = parentState.hashes
|
|
235
|
+
this.entries = parentState.entries
|
|
236
|
+
this.modules = parentState.modules
|
|
237
|
+
// Inherit, via the parent's public sidecarInheritance() so it works across copies:
|
|
238
|
+
// - preloadRoot, so plugin-driven write()s (StasisWebpack / StasisEsbuild done-hook
|
|
239
|
+
// saves) backfill stasis-core's internal edges the same way the parent does;
|
|
240
|
+
// - the lockfile attestation maps, so #mergeBundleMetadata cross-checks the sidecar
|
|
241
|
+
// bundle against the same attestation the parent loaded -- without this a tampered
|
|
242
|
+
// sidecar bundle could redirect a resolution or flip a format (commonjs <->
|
|
243
|
+
// module-typescript) for hash-valid bytes, which the byte check alone misses.
|
|
244
|
+
const inherited = parentState.sidecarInheritance()
|
|
245
|
+
this.#preloadRoot = inherited.preloadRoot
|
|
246
|
+
this.#lockImports = inherited.lockImports
|
|
247
|
+
this.#lockFormats = inherited.lockFormats
|
|
248
|
+
this.#lockfileLoaded = inherited.lockfileLoaded
|
|
249
|
+
assert.ok(this.config.bundleFile, 'sidecar State requires bundleFile')
|
|
250
|
+
// Claim the bundleFile (and resourcesBundleFile under the split layout) against the
|
|
251
|
+
// process-wide registry so two write-intent States anywhere -- whether a sibling
|
|
252
|
+
// sidecar or an independent top-level State (a CLI/env run with a custom
|
|
253
|
+
// lockfile/bundle path) -- can't silently target the same on-disk file
|
|
254
|
+
// (last-write-wins on `beforeExit`). Only writing States claim; read-only modes
|
|
255
|
+
// (load / frozen) may legitimately share a path with the writer that produced the
|
|
256
|
+
// file. The Config's own pairwise cross-path check (config.js:#checkInvariants)
|
|
257
|
+
// already rejects intra-State collisions, so #claimWritePath only fires on
|
|
258
|
+
// cross-State conflicts.
|
|
259
|
+
if (this.config.writeBundle) {
|
|
260
|
+
this.#claimWritePath(`sidecar bundleFile '${this.config.bundleFile}'`, this.config.bundleFile)
|
|
261
|
+
if (this.config.resourcesBundleFile) {
|
|
262
|
+
this.#claimWritePath(`sidecar resourcesBundleFile '${this.config.resourcesBundleFile}'`,
|
|
263
|
+
this.config.resourcesBundleFile)
|
|
264
|
+
}
|
|
265
|
+
}
|
|
266
|
+
// frozenBundle MUST go through this branch alongside write/load -- it has its
|
|
267
|
+
// own attestation snapshot to build, and was previously missed (silently
|
|
268
|
+
// skipping parsing made the post-construction frozen-bundle invariant
|
|
269
|
+
// unreachable on the sidecar path).
|
|
270
|
+
if (this.config.writeBundle || this.config.loadBundle || this.config.frozenBundle) {
|
|
271
|
+
const sourcesPath = this.config.bundleFile
|
|
272
|
+
const sources = readFileSyncMaybe(dirname(sourcesPath), basename(sourcesPath))
|
|
273
|
+
if (sources && !this.config.replaceBundle) {
|
|
274
|
+
const bundle = Bundle.parse(brotliDecompressSync(sources).toString('utf-8'))
|
|
275
|
+
// Same v0 refusal as the main load path: a v0 bundle has no per-file
|
|
276
|
+
// formats and no import map, so serving / verifying one through a
|
|
277
|
+
// sidecar would silently widen trust.
|
|
278
|
+
assert.equal(bundle.version, Bundle.VERSION,
|
|
279
|
+
`stasis sidecar requires a v1 bundle; ${sourcesPath} is v${bundle.version}. ` +
|
|
280
|
+
`Re-bundle with the current stasis or \`bundle=replace\` against a v0-free starting point.`)
|
|
281
|
+
assert.equal(bundle.config.scope, this.config.scope)
|
|
282
|
+
// Cross-check the sidecar bundle's metadata against the parent's lockfile
|
|
283
|
+
// (or absorb if no lockfile was loaded). hashes/entries/modules are shared
|
|
284
|
+
// with the parent, so #mergeBundleMetadata's writes -- when no lockfile is
|
|
285
|
+
// loaded -- propagate into the unified attestation.
|
|
286
|
+
this.#mergeBundleMetadata(bundle, { lockfileLoaded: this.#lockfileLoaded })
|
|
287
|
+
for (const [file, content] of bundle.sources) {
|
|
288
|
+
if (Bundle.isResourceFormat(bundle.formats.get(file))) this.resources.set(file, content)
|
|
289
|
+
else this.sources.set(file, content)
|
|
290
|
+
}
|
|
291
|
+
this.formats = bundle.formats
|
|
292
|
+
this.imports = bundle.imports
|
|
293
|
+
if (this.config.frozenBundle) {
|
|
294
|
+
// Same snapshot the main path takes -- closes the attested set so
|
|
295
|
+
// addFile/addImport reject anything the bundle didn't carry.
|
|
296
|
+
this.#bundleSources = new Set(this.sources.keys())
|
|
297
|
+
this.#bundleResources = new Set(this.resources.keys())
|
|
298
|
+
this.#bundleImports = objectToMaps(fileMapToObject(bundle.imports))
|
|
299
|
+
this.#bundleFormats = new Map(bundle.formats)
|
|
300
|
+
}
|
|
301
|
+
}
|
|
302
|
+
|
|
303
|
+
// Sidecar split-bundle: same shape as the main path's resources-side load.
|
|
304
|
+
if (this.config.resourcesBundleFile) {
|
|
305
|
+
const resourcesPath = this.config.resourcesBundleFile
|
|
306
|
+
const resourcesData = readFileSyncMaybe(dirname(resourcesPath), basename(resourcesPath))
|
|
307
|
+
if (resourcesData && !this.config.replaceBundle) {
|
|
308
|
+
this.#absorbResourcesBundle(resourcesData, { lockfileLoaded: this.#lockfileLoaded, resourcesPath })
|
|
309
|
+
}
|
|
310
|
+
}
|
|
311
|
+
}
|
|
312
|
+
// Mirror the post-discovery invariant from the main path: frozen modes must
|
|
313
|
+
// have actually loaded their attestation, otherwise the run would fail open.
|
|
314
|
+
if (this.config.frozenBundle) {
|
|
315
|
+
assert.ok(this.#bundleSources !== null, 'No bundle, but attempting to run in frozen bundle mode')
|
|
316
|
+
}
|
|
317
|
+
// Register with the parent AFTER every fallible step (v0 refusal, scope
|
|
318
|
+
// equality, #mergeBundleMetadata cross-check, frozenBundle invariant) so a
|
|
319
|
+
// throw never leaves a dead reference in the parent's registries.
|
|
320
|
+
// Write-mode sidecars are lockfile CONTRIBUTORS -- their addImport / addFile
|
|
321
|
+
// observations have to land in the unified lockfile, otherwise a `lock=frozen`
|
|
322
|
+
// re-run rejects them as unattested -- so they join #sidecars (which feeds
|
|
323
|
+
// #mergedImports/#mergedFormats and attestedBySidecar). Load-mode sidecars are
|
|
324
|
+
// CONSUMERS: they must NOT contribute to the parent's lockfile (the bundle has
|
|
325
|
+
// its own integrity story, and under `lock=add` with no prior lockfile a
|
|
326
|
+
// load-mode sidecar would otherwise silently make the bundle's content the
|
|
327
|
+
// lockfile's source of truth), but they DO carry bundle bytes that --fs serves at
|
|
328
|
+
// load, so they join the read-only #readSidecars (consulted by getFs*Family only).
|
|
329
|
+
// Frozen sidecars join neither: --fs neither captures nor serves in frozen-bundle
|
|
330
|
+
// mode (fs.js gates capture on writeBundle and serve on loadBundle), and their
|
|
331
|
+
// lockfile cross-check already happened in #mergeBundleMetadata above.
|
|
332
|
+
if (this.config.writeBundle) parentState.registerSidecar(this)
|
|
333
|
+
else if (this.config.loadBundle) parentState.registerReadSidecar(this)
|
|
334
|
+
liveStates().add(this)
|
|
335
|
+
return
|
|
336
|
+
}
|
|
337
|
+
|
|
338
|
+
// skipDiscovery (see the constructor comment): a caller-populated, in-memory State.
|
|
339
|
+
// Skip the entire filesystem-discovery path -- anchor at the given root, read nothing --
|
|
340
|
+
// and let the caller fill in the maps. Only sound for read-only load/ignore modes:
|
|
341
|
+
// there is no on-disk attestation to load or verify, so frozen modes are rejected.
|
|
342
|
+
if (skipDiscovery) {
|
|
343
|
+
// Read-only by contract: a caller-populated in-memory State has no on-disk baseline,
|
|
344
|
+
// so neither frozen verification (nothing to verify against) nor write modes (nothing
|
|
345
|
+
// discovered to write) are meaningful. `stasis build` uses bundle:'load', lock:'ignore'.
|
|
346
|
+
assert.ok(!this.config.frozen && !this.config.frozenBundle && !this.config.writeBundle && !this.config.writeLockfile,
|
|
347
|
+
'skipDiscovery is read-only: incompatible with frozen and write (add/replace) lock/bundle modes')
|
|
348
|
+
this.root = resolve(root)
|
|
349
|
+
if (preloadRoot !== undefined) {
|
|
350
|
+
assert.equal(typeof preloadRoot, 'string', 'preloadRoot must be a string')
|
|
351
|
+
this.#preloadRoot = preloadRoot
|
|
352
|
+
}
|
|
353
|
+
liveStates().add(this)
|
|
354
|
+
return
|
|
355
|
+
}
|
|
356
|
+
|
|
357
|
+
// Preload-uniqueness invariant must be checked before construction proceeds; the
|
|
358
|
+
// actual liveStates() registration happens after construction succeeds so a throw in
|
|
359
|
+
// setup can't leave a half-built (and, for a preload, singleton-claiming) State behind.
|
|
360
|
+
const potentialRoots = []
|
|
361
|
+
let cursor = root
|
|
362
|
+
while (cursor) {
|
|
363
|
+
if (existsSync(join(cursor, 'package.json'))) {
|
|
364
|
+
potentialRoots.push(cursor)
|
|
365
|
+
} else if (
|
|
366
|
+
existsSync(join(cursor, FILE_CONFIG)) ||
|
|
367
|
+
existsSync(join(cursor, FILE_LOCK)) ||
|
|
368
|
+
existsSync(join(cursor, FILE_CODE))) {
|
|
369
|
+
throw new Error('Unexpected stasis config without package.json')
|
|
370
|
+
}
|
|
371
|
+
|
|
372
|
+
if (cursor === process.env.PROJECT_CWD) break // e.g. yarn sets this
|
|
373
|
+
if (existsSync(join(cursor, '.git'))) break // don't go higher than the repo root
|
|
374
|
+
if (existsSync(join(cursor, 'pnpm-workspace.yaml'))) break // pnpm workspace root
|
|
375
|
+
const parent = dirname(cursor)
|
|
376
|
+
if (!parent || parent === cursor) break
|
|
377
|
+
cursor = parent
|
|
378
|
+
}
|
|
379
|
+
|
|
380
|
+
// default root is top-level package.json, to opt-in to per-dir create stasis.config.json
|
|
381
|
+
this.root = potentialRoots.at(-1)
|
|
382
|
+
|
|
383
|
+
let loaded = false
|
|
384
|
+
let lockfileLoaded = false
|
|
385
|
+
// When `config.lockFile` is set, the lockfile lives at that explicit path -- not at
|
|
386
|
+
// join(rootDir, FILE_LOCK) for any candidate rootDir. Suppress the per-rootDir read
|
|
387
|
+
// for root-detection (so a stale stasis.lock.json at the project root can't shadow
|
|
388
|
+
// the explicit one), then substitute the explicit content once root-detection has
|
|
389
|
+
// committed to a rootDir below.
|
|
390
|
+
const explicitLockPath = this.config.lockFile
|
|
391
|
+
// A construction-time `bundleFile` (a --bundle-file flag or EXODUS_STASIS_BUNDLE_FILE) is
|
|
392
|
+
// rootDir-INDEPENDENT: reading it yields the same file at every candidate root. So, exactly
|
|
393
|
+
// like explicitLockPath, it must NOT act as a per-rootDir root-detection signal -- if it did,
|
|
394
|
+
// the innermost package.json dir would always match first and win, diverging load's root from
|
|
395
|
+
// the (outer) root the bundle was captured with. Because every bundle key is stored relative
|
|
396
|
+
// to the capture root, that divergence makes every bundled dependency unreachable at load: the
|
|
397
|
+
// load hook throws "outside project root" / "not attested", and Node's ESM->CJS translator --
|
|
398
|
+
// which re-resolves a required dependency through Module._load(absPath, /* no parent */) -- hits
|
|
399
|
+
// native disk resolution for a file the bundle carries but disk (post-prune / never-shipped)
|
|
400
|
+
// does not, i.e. `Cannot find module '<abs node_modules path>'`. Root is instead chosen from
|
|
401
|
+
// rootDir-DEPENDENT signals (stasis.config.json, the default lockfile/bundle at the dir), then
|
|
402
|
+
// the explicit bundle is loaded at the committed root -- or, when nothing else committed, at the
|
|
403
|
+
// outermost root post-loop (mirroring explicitLockPath). A `bundleFile` that comes only from
|
|
404
|
+
// stasis.config.json is NOT suppressed: it lives at a dir already carrying the config signal, so
|
|
405
|
+
// it selects that dir consistently at capture and load alike.
|
|
406
|
+
const explicitBundlePath = this.config.bundleFile
|
|
407
|
+
for (const rootDir of potentialRoots) {
|
|
408
|
+
const config = readFileSyncMaybe(rootDir, FILE_CONFIG, 'utf-8')
|
|
409
|
+
const lockProbe = explicitLockPath ? null : readFileSyncMaybe(rootDir, FILE_LOCK, 'utf-8')
|
|
410
|
+
// Read the bundle at the construction-time bundleFile (a --bundle-file flag or
|
|
411
|
+
// EXODUS_STASIS_BUNDLE_FILE) or, absent that, the default <rootDir>/stasis.code.br -- used
|
|
412
|
+
// to LOAD the bundle once a root is committed. The authoritative path can still change when
|
|
413
|
+
// loadConfig() applies a `bundleFile` from stasis.config.json, so it's re-read below.
|
|
414
|
+
let sourcesPath = this.config.bundleFile || join(rootDir, FILE_CODE)
|
|
415
|
+
let sources = readFileSyncMaybe(dirname(sourcesPath), basename(sourcesPath))
|
|
416
|
+
// Root-SELECTION signal: only the DEFAULT <rootDir>/stasis.code.br counts. An explicit
|
|
417
|
+
// (rootDir-independent) bundleFile is suppressed here (see explicitBundlePath above) so it
|
|
418
|
+
// can't bias selection to the innermost dir; it is still loaded via `sources` once committed.
|
|
419
|
+
const bundleProbe = explicitBundlePath ? null : sources
|
|
420
|
+
if (config !== null || lockProbe !== null || bundleProbe !== null) {
|
|
421
|
+
if (loaded) throw new Error('Stasis config already loaded')
|
|
422
|
+
loaded = true
|
|
423
|
+
this.root = rootDir
|
|
424
|
+
|
|
425
|
+
if (config) {
|
|
426
|
+
this.config.loadConfig(config)
|
|
427
|
+
// stasis.config.json may set `bundleFile`, which the probe above (using the
|
|
428
|
+
// construction-time value) could not see. Re-resolve against the now-authoritative
|
|
429
|
+
// config and re-read, so a config-only bundleFile is honored for load/frozen -- the
|
|
430
|
+
// write side (state.write) already resolves bundleFile after loadConfig. This mirrors
|
|
431
|
+
// the resourcesBundleFile read below, which is naturally post-loadConfig.
|
|
432
|
+
const configuredPath = this.config.bundleFile || join(rootDir, FILE_CODE)
|
|
433
|
+
if (configuredPath !== sourcesPath) {
|
|
434
|
+
sourcesPath = configuredPath
|
|
435
|
+
sources = readFileSyncMaybe(dirname(sourcesPath), basename(sourcesPath))
|
|
436
|
+
}
|
|
437
|
+
}
|
|
438
|
+
|
|
439
|
+
// Resolve the effective lockfile content + path for this run. With an explicit
|
|
440
|
+
// `config.lockFile`, the lockfile is at that exact path (loaded once, not at a
|
|
441
|
+
// per-rootDir probe); without one, fall back to `<rootDir>/stasis.lock.json`.
|
|
442
|
+
const lock = explicitLockPath
|
|
443
|
+
? readFileSyncMaybe(dirname(explicitLockPath), basename(explicitLockPath), 'utf-8')
|
|
444
|
+
: lockProbe
|
|
445
|
+
const lockPath = explicitLockPath || join(rootDir, FILE_LOCK)
|
|
446
|
+
|
|
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
|
+
}
|
|
512
|
+
|
|
513
|
+
// The innermost matching rootDir is authoritative (per-dir opt-in, see above), so stop
|
|
514
|
+
// scanning once committed. An explicit/config `bundleFile` is rootDir-independent: without
|
|
515
|
+
// this break an outer candidate root re-detects the SAME bundle file at its own probe and
|
|
516
|
+
// trips the `loaded` guard above -- which crashed bundle=load/frozen in any nested-package
|
|
517
|
+
// (monorepo) layout where a leaf package sits under an ancestor that also has a package.json.
|
|
518
|
+
break
|
|
519
|
+
}
|
|
520
|
+
}
|
|
521
|
+
|
|
522
|
+
// Explicit lockfile path with no other discovery indicator at any rootDir: the
|
|
523
|
+
// discovery loop never set `loaded`, so the lockfile branch above never ran. Process
|
|
524
|
+
// 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.
|
|
527
|
+
if (!loaded && explicitLockPath) {
|
|
528
|
+
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
|
+
}
|
|
586
|
+
}
|
|
587
|
+
|
|
588
|
+
// Frozen modes must have actually loaded their attestation. Asserting here --
|
|
589
|
+
// after the discovery loop -- rather than only inside it closes a fail-open: with
|
|
590
|
+
// no stasis files on disk at all the loop body never runs, so a per-rootDir guard
|
|
591
|
+
// would never fire, and in node_modules scope the workspace entry sits outside the
|
|
592
|
+
// attested zone (its bytes/format/resolutions aren't checked), letting it execute
|
|
593
|
+
// unverified. A frozen run with nothing to verify against must fail closed instead.
|
|
594
|
+
if (this.config.frozen) assert.ok(lockfileLoaded, 'No lockfile, but attempting to run in frozen mode')
|
|
595
|
+
if (this.config.frozenBundle) assert.ok(this.#bundleSources !== null, 'No bundle, but attempting to run in frozen bundle mode')
|
|
596
|
+
|
|
597
|
+
// Claim this State's write targets against the process-wide registry (liveStates),
|
|
598
|
+
// so a sidecar OR an independent top-level State -- in this OR another stasis-core
|
|
599
|
+
// copy -- can't silently target the same on-disk file. Load / frozen / no-bundle modes
|
|
600
|
+
// don't claim (they legitimately read what a previous writer produced). lockFile is
|
|
601
|
+
// claimed only by writing top-level States -- sidecars don't write the lockfile, and
|
|
602
|
+
// the explicit path may legitimately point at the parent's under unification. The
|
|
603
|
+
// State itself is added to liveStates() below, AFTER every fallible step (including
|
|
604
|
+
// these claims), so a throw during discovery/parsing/claiming never leaves a dead member.
|
|
605
|
+
if (this.config.writeBundle && this.config.bundleFile) {
|
|
606
|
+
this.#claimWritePath(`bundleFile '${this.config.bundleFile}'`, this.config.bundleFile)
|
|
607
|
+
}
|
|
608
|
+
if (this.config.writeBundle && this.config.resourcesBundleFile) {
|
|
609
|
+
this.#claimWritePath(`resourcesBundleFile '${this.config.resourcesBundleFile}'`, this.config.resourcesBundleFile)
|
|
610
|
+
}
|
|
611
|
+
if (this.config.writeLockfile && this.config.lockFile) {
|
|
612
|
+
this.#claimWritePath(`lockFile '${this.config.lockFile}'`, this.config.lockFile)
|
|
613
|
+
}
|
|
614
|
+
|
|
615
|
+
// preloadRoot is opt-in -- only the runtime loader (hooks.js's initState)
|
|
616
|
+
// sets it, pointing at stasis-core's own package root. Plain top-level
|
|
617
|
+
// States constructed via the CLI / direct API leave it null and skip
|
|
618
|
+
// the internal-edges backfill entirely.
|
|
619
|
+
if (preloadRoot !== undefined) {
|
|
620
|
+
assert.equal(typeof preloadRoot, 'string', 'preloadRoot must be a string')
|
|
621
|
+
this.#preloadRoot = preloadRoot
|
|
622
|
+
}
|
|
623
|
+
|
|
624
|
+
liveStates().add(this)
|
|
625
|
+
}
|
|
626
|
+
|
|
627
|
+
// Absorb a unified code+resource bundle's metadata and payloads into this State. Shared by the
|
|
628
|
+
// discovery loop (a committed rootDir carrying a stasis signal) and the post-loop fallback that
|
|
629
|
+
// loads an explicit (rootDir-independent) bundleFile against the outermost root.
|
|
630
|
+
#absorbCodeBundle(sources, sourcesPath, lockfileLoaded) {
|
|
631
|
+
// One unified bundle carries both code and resources. Split the flat file
|
|
632
|
+
// view into this.sources (code) and this.resources (resource payloads --
|
|
633
|
+
// raw UTF-8 for 'resource', base64 for 'resource:base64') by format.
|
|
634
|
+
const bundle = Bundle.parse(brotliDecompressSync(sources).toString('utf-8'))
|
|
635
|
+
// `Bundle.parse` accepts v0 for offline tooling (`stasis extract`, `diff`,
|
|
636
|
+
// `audit`, `sbom`) -- it has the metadata those commands need. The runtime
|
|
637
|
+
// path is stricter: a v0 bundle has no per-file `formats` attestation
|
|
638
|
+
// (resources can't be distinguished from code, the loader can't pick
|
|
639
|
+
// module-vs-commonjs) and no import map (resolution edges go unchecked),
|
|
640
|
+
// so serving / verifying one under `stasis run` would silently widen the
|
|
641
|
+
// trust boundary. Refuse it explicitly and point at the upgrade path.
|
|
642
|
+
assert.equal(bundle.version, Bundle.VERSION,
|
|
643
|
+
`stasis run requires a v1 bundle; ${sourcesPath} is v${bundle.version}. ` +
|
|
644
|
+
`Re-bundle with the current stasis (\`stasis bundle\`) or \`stasis run --bundle=replace\` ` +
|
|
645
|
+
`against a v0-free starting point to upgrade.`)
|
|
646
|
+
assert.equal(bundle.config.scope, this.config.scope)
|
|
647
|
+
this.#mergeBundleMetadata(bundle, { lockfileLoaded })
|
|
648
|
+
for (const [file, content] of bundle.sources) {
|
|
649
|
+
if (Bundle.isResourceFormat(bundle.formats.get(file))) this.resources.set(file, content)
|
|
650
|
+
else this.sources.set(file, content)
|
|
651
|
+
}
|
|
652
|
+
this.formats = bundle.formats
|
|
653
|
+
this.imports = bundle.imports
|
|
654
|
+
if (this.config.frozenBundle) {
|
|
655
|
+
// Snapshot the attested sets before addFile/addImport mutate the live maps.
|
|
656
|
+
// imports is deep-cloned (this.imports shares bundle.imports's nested Maps,
|
|
657
|
+
// which addImport extends); formats is a flat file->string map, so a shallow
|
|
658
|
+
// copy suffices. Code and resource file sets are tracked separately to match
|
|
659
|
+
// addFile's per-kind frozen-bundle membership check.
|
|
660
|
+
this.#bundleSources = new Set(this.sources.keys())
|
|
661
|
+
this.#bundleResources = new Set(this.resources.keys())
|
|
662
|
+
this.#bundleImports = objectToMaps(fileMapToObject(bundle.imports))
|
|
663
|
+
this.#bundleFormats = new Map(bundle.formats)
|
|
664
|
+
}
|
|
665
|
+
}
|
|
666
|
+
|
|
667
|
+
// Cross-check bundle metadata (entries/modules) with what the lockfile already
|
|
668
|
+
// loaded, or absorb it as the source of truth when no lockfile is present.
|
|
669
|
+
// v0 bundles infer `name` from path for node_modules buckets but carry no
|
|
670
|
+
// version; the workspace "." bucket has no inferable name. We skip entries
|
|
671
|
+
// we can't cross-check (no name with lockfile, or no version when populating
|
|
672
|
+
// state.modules — addFile later asserts strict name+version equality against
|
|
673
|
+
// disk's package.json, which would clash with a null we stashed earlier).
|
|
674
|
+
// Note: the path-inferred name for v0 will disagree with the lockfile when a
|
|
675
|
+
// dep is installed under an alias (`foo: npm:bar` writes `node_modules/foo`
|
|
676
|
+
// with `name: "bar"` in package.json); the strict equality below will fail
|
|
677
|
+
// in that case, which is the right call — the v0 bundle has no way to
|
|
678
|
+
// attest the real package identity, so we refuse to silently mismatch.
|
|
679
|
+
#mergeBundleMetadata(bundle, { lockfileLoaded }) {
|
|
680
|
+
if (lockfileLoaded) {
|
|
681
|
+
if (bundle.entries.size > 0) {
|
|
682
|
+
assert.deepStrictEqual(
|
|
683
|
+
[...bundle.entries].toSorted(),
|
|
684
|
+
[...this.entries].toSorted(),
|
|
685
|
+
'bundle/lockfile entries mismatch'
|
|
686
|
+
)
|
|
687
|
+
}
|
|
688
|
+
for (const [dir, info] of bundle.modules) {
|
|
689
|
+
if (!info.name) continue // workspace bucket or fallback: no inferable name
|
|
690
|
+
assert.ok(this.modules.has(dir), `bundle module ${dir} missing in lockfile`)
|
|
691
|
+
const lockModule = this.modules.get(dir)
|
|
692
|
+
assert.equal(info.name, lockModule.name)
|
|
693
|
+
if (info.version) assert.equal(info.version, lockModule.version)
|
|
694
|
+
for (const rel of Object.keys(info.files)) {
|
|
695
|
+
assert.ok(Object.hasOwn(lockModule.files, rel), `bundle file ${dir}/${rel} missing in lockfile`)
|
|
696
|
+
}
|
|
697
|
+
}
|
|
698
|
+
// Resolutions: every edge the bundle could serve must land on the file
|
|
699
|
+
// the lockfile attests for that (parent, specifier) -- source hashes
|
|
700
|
+
// alone don't close this hole: a tampered bundle could redirect a
|
|
701
|
+
// specifier to a *different* hash-valid file. Unknown edges are fatal.
|
|
702
|
+
// The lockfile may attest a superset (same stance as the file lists
|
|
703
|
+
// above). Lockfiles that predate resolution attestation
|
|
704
|
+
// (imports === null) skip the check -- regenerate with lock=replace.
|
|
705
|
+
if (this.#lockImports !== null) {
|
|
706
|
+
for (const [conditions, byParent] of bundle.imports) {
|
|
707
|
+
for (const [parent, specifiers] of byParent) {
|
|
708
|
+
for (const [specifier, file] of specifiers) {
|
|
709
|
+
this.#assertAttestedResolution(this.#lockImports, conditions, parent, specifier, file, { what: 'bundle', source: 'lockfile' })
|
|
710
|
+
}
|
|
711
|
+
}
|
|
712
|
+
}
|
|
713
|
+
}
|
|
714
|
+
// Formats: the loader picks module<->commonjs and (for *-typescript)
|
|
715
|
+
// whether Node strips type syntax purely from this map, so a tampered
|
|
716
|
+
// bundle can change how hash-valid bytes parse/run without touching a
|
|
717
|
+
// hash. Every format the bundle declares must match the lockfile's. The
|
|
718
|
+
// bundle's file set is a subset of the lockfile, so an unattested format
|
|
719
|
+
// is fatal here (it can only mean a forged entry).
|
|
720
|
+
if (this.#lockFormats !== null) {
|
|
721
|
+
for (const [file, format] of bundle.formats) {
|
|
722
|
+
this.#assertAttestedFormat(this.#lockFormats, file, format, { what: 'bundle', source: 'lockfile' })
|
|
723
|
+
}
|
|
724
|
+
// Inverse direction: if the lockfile tags a file the bundle carries as a
|
|
725
|
+
// resource, the bundle MUST declare the matching resource format. Without
|
|
726
|
+
// this, a tampered bundle could OMIT the resource tag entirely -- State.load
|
|
727
|
+
// would then see no resource format, route the base64 payload through
|
|
728
|
+
// `this.sources` (the code path), and hand it to the loader. Caught at the
|
|
729
|
+
// loader's NODEJS_FORMATS gate too, but checking here surfaces it as a clean
|
|
730
|
+
// bundle/lockfile mismatch rather than as an opaque "unknown format" later.
|
|
731
|
+
// (We don't extend this to code formats: doing so would mean asserting
|
|
732
|
+
// `formats` is total over `modules`, which is a stronger schema invariant
|
|
733
|
+
// than the historical "format may be missing per file" contract -- and the
|
|
734
|
+
// code-format hole is closed by the loader allowlist anyway.)
|
|
735
|
+
for (const [dir, { files }] of bundle.modules) {
|
|
736
|
+
for (const rel of Object.keys(files)) {
|
|
737
|
+
const file = moduleFileKey(dir, rel)
|
|
738
|
+
const lockFormat = this.#lockFormats.get(file)
|
|
739
|
+
if (!Bundle.isResourceFormat(lockFormat)) continue
|
|
740
|
+
assert.equal(bundle.formats.get(file), lockFormat,
|
|
741
|
+
`bundle file ${file} must declare format='${lockFormat}' to match the lockfile`)
|
|
742
|
+
}
|
|
743
|
+
}
|
|
744
|
+
}
|
|
745
|
+
} else {
|
|
746
|
+
// Mutate in place rather than reassigning -- this.entries may be shared by
|
|
747
|
+
// reference with a sidecar's parent (the unified-lockfile model), and a
|
|
748
|
+
// reassignment would silently fork the shared set.
|
|
749
|
+
for (const e of bundle.entries) this.entries.add(e)
|
|
750
|
+
for (const [dir, info] of bundle.modules) {
|
|
751
|
+
if (!info.name || !info.version) continue // partial metadata
|
|
752
|
+
if (this.modules.has(dir)) {
|
|
753
|
+
// A unified bundle populates `state.modules` from both its code and resource
|
|
754
|
+
// entries; if the same dir is added twice (e.g. legacy duplicated metadata)
|
|
755
|
+
// they must agree on name/version.
|
|
756
|
+
const existing = this.modules.get(dir)
|
|
757
|
+
assert.equal(info.name, existing.name, `bundle ${dir} name mismatch`)
|
|
758
|
+
assert.equal(info.version, existing.version, `bundle ${dir} version mismatch`)
|
|
759
|
+
} else {
|
|
760
|
+
this.modules.set(dir, info.ecosystem === undefined
|
|
761
|
+
? { name: info.name, version: info.version, files: Object.create(null) }
|
|
762
|
+
: { name: info.name, version: info.version, ecosystem: info.ecosystem, files: Object.create(null) })
|
|
763
|
+
}
|
|
764
|
+
}
|
|
765
|
+
}
|
|
766
|
+
}
|
|
767
|
+
|
|
768
|
+
// Load the resources side of a split-bundle layout: a standalone Bundle file
|
|
769
|
+
// that MUST hold only resource-format files (no entries, no imports, no
|
|
770
|
+
// code-format declarations). Unions into the state already absorbed from
|
|
771
|
+
// `bundleFile`, extending this.resources, this.formats, and -- under
|
|
772
|
+
// frozenBundle -- the attestation snapshots. The shape asserts catch a writer
|
|
773
|
+
// that leaked code into the resources file or a tampered file claiming
|
|
774
|
+
// metadata it shouldn't carry.
|
|
775
|
+
#absorbResourcesBundle(resourcesData, { lockfileLoaded, resourcesPath }) {
|
|
776
|
+
const bundle = Bundle.parse(brotliDecompressSync(resourcesData).toString('utf-8'))
|
|
777
|
+
assert.equal(bundle.version, Bundle.VERSION,
|
|
778
|
+
`stasis run requires a v1 resources bundle; ${resourcesPath} is v${bundle.version}. ` +
|
|
779
|
+
`Re-bundle with the current stasis or \`bundle=replace\` against a v0-free starting point to upgrade.`)
|
|
780
|
+
assert.equal(bundle.config.scope, this.config.scope)
|
|
781
|
+
// Resources file MUST NOT declare resolution edges or entry points -- those
|
|
782
|
+
// belong to the code bundle. A populated map here means the writer mixed
|
|
783
|
+
// halves (or the file was tampered with) and serving it would silently widen
|
|
784
|
+
// trust on the code-bundle side's metadata.
|
|
785
|
+
assert.equal(bundle.imports.size, 0, `resources bundle ${resourcesPath} must have empty imports`)
|
|
786
|
+
assert.equal(bundle.entries.size, 0, `resources bundle ${resourcesPath} must have empty entries`)
|
|
787
|
+
for (const [file, format] of bundle.formats) {
|
|
788
|
+
assert.ok(Bundle.isResourceFormat(format),
|
|
789
|
+
`resources bundle ${resourcesPath} declares non-resource format='${format}' for ${file}`)
|
|
790
|
+
}
|
|
791
|
+
this.#mergeBundleMetadata(bundle, { lockfileLoaded })
|
|
792
|
+
for (const [file, content] of bundle.sources) {
|
|
793
|
+
this.resources.set(file, content)
|
|
794
|
+
}
|
|
795
|
+
// Union formats: conflict-free (bundleFile carries code formats, this one carries
|
|
796
|
+
// resource formats -- the file sets must be disjoint).
|
|
797
|
+
for (const [file, format] of bundle.formats) {
|
|
798
|
+
const existing = this.formats.get(file)
|
|
799
|
+
assert.ok(existing === undefined || existing === format,
|
|
800
|
+
`format conflict for ${file}: bundleFile declares '${existing}', resourcesBundleFile declares '${format}'`)
|
|
801
|
+
this.formats.set(file, format)
|
|
802
|
+
}
|
|
803
|
+
if (this.config.frozenBundle) {
|
|
804
|
+
// Extend the frozen snapshot. bundleFile's path may not have populated these
|
|
805
|
+
// (resources-only deployments are legal -- only the resources file exists),
|
|
806
|
+
// so initialize lazily; #bundleSources may stay null in that case, which the
|
|
807
|
+
// post-discovery invariant check accepts because #bundleResources is set.
|
|
808
|
+
if (this.#bundleResources === null) this.#bundleResources = new Set()
|
|
809
|
+
if (this.#bundleFormats === null) this.#bundleFormats = new Map()
|
|
810
|
+
if (this.#bundleImports === null) this.#bundleImports = objectToMaps(fileMapToObject(this.imports))
|
|
811
|
+
if (this.#bundleSources === null) this.#bundleSources = new Set(this.sources.keys())
|
|
812
|
+
for (const f of bundle.sources.keys()) this.#bundleResources.add(f)
|
|
813
|
+
for (const [f, fmt] of bundle.formats) this.#bundleFormats.set(f, fmt)
|
|
814
|
+
}
|
|
815
|
+
}
|
|
816
|
+
|
|
817
|
+
// Verify one resolution edge against an attestation map (`source`: a loaded
|
|
818
|
+
// lockfile, or a frozen bundle's own recorded imports). The final resolution
|
|
819
|
+
// is what matters, not how the edge is keyed: the conditions key is matched
|
|
820
|
+
// exactly first; on a miss the edge is accepted only when every condition set
|
|
821
|
+
// the attestation records for that (parent, specifier) agrees on the same
|
|
822
|
+
// target -- this lets a static `stasis bundle` artifact (edges under '*')
|
|
823
|
+
// validate against a runtime-generated attestation (precise condition sets),
|
|
824
|
+
// and vice versa, while a claim over a condition-divergent attestation stays
|
|
825
|
+
// fatal: either target would be served under conditions where the other is
|
|
826
|
+
// the attested resolution. Unknown edges are fatal unless the caller opts out
|
|
827
|
+
// (see addImport's node_modules-scope carve-out).
|
|
828
|
+
#assertAttestedResolution(attestation, conditions, parent, specifier, file, { what, source = 'lockfile', tolerateUnknown = false }) {
|
|
829
|
+
const edge = `'${specifier}' from ${parent} (${conditions})`
|
|
830
|
+
let attested = attestation.get(conditions)?.get(parent)?.get(specifier)
|
|
831
|
+
if (attested === undefined) {
|
|
832
|
+
const targets = new Set()
|
|
833
|
+
for (const [, parents] of attestation) {
|
|
834
|
+
const target = parents.get(parent)?.get(specifier)
|
|
835
|
+
if (target !== undefined) targets.add(target)
|
|
836
|
+
}
|
|
837
|
+
if (targets.size === 0 && tolerateUnknown) return
|
|
838
|
+
assert.ok(targets.size > 0, `${what} resolution ${edge} is not attested by the ${source}`)
|
|
839
|
+
assert.ok(targets.size === 1, `${what} resolution ${edge} is attested inconsistently across condition sets in the ${source}`)
|
|
840
|
+
;[attested] = targets
|
|
841
|
+
}
|
|
842
|
+
// A per-platform edge is a Map<platform, target>; compare it structurally -- a plain
|
|
843
|
+
// assert.equal is reference equality, so two identical Maps (the bundle's edge and the
|
|
844
|
+
// lockfile's) would never match. A flat string edge stays a plain ===; a Map-vs-string
|
|
845
|
+
// (e.g. a per-platform attestation vs a single observed runtime target) is a mismatch.
|
|
846
|
+
const matches = file instanceof Map && attested instanceof Map
|
|
847
|
+
? file.size === attested.size && [...file].every(([platform, target]) => attested.get(platform) === target)
|
|
848
|
+
: file === attested
|
|
849
|
+
assert.ok(matches, `${what} resolution ${edge} mismatches the ${source}`)
|
|
850
|
+
}
|
|
851
|
+
|
|
852
|
+
// Verify one file's loader format against an attestation map (`source`: a
|
|
853
|
+
// loaded lockfile, or a frozen bundle's own recorded formats). Callers only
|
|
854
|
+
// invoke this for files that must be attested (the attestation is a superset
|
|
855
|
+
// of any bundle, and on the disk path the call is gated to the hash-attested
|
|
856
|
+
// zone), so an unattested file means a forged/extra entry and is fatal.
|
|
857
|
+
#assertAttestedFormat(attestation, file, format, { what, source = 'lockfile' }) {
|
|
858
|
+
const attested = attestation.get(file)
|
|
859
|
+
assert.ok(attested !== undefined, `${what} format for ${file} is not attested by the ${source}`)
|
|
860
|
+
assert.equal(format, attested, `${what} format for ${file} mismatches the ${source}`)
|
|
861
|
+
}
|
|
862
|
+
|
|
863
|
+
assertEntry(url) {
|
|
864
|
+
// Skipped silently when no entries info is available (v0 bundle + lock=none/ignore).
|
|
865
|
+
// v1 bundles in full scope are required to declare at least one entry at parse time,
|
|
866
|
+
// so this fallback only ever triggers for the legacy path.
|
|
867
|
+
if (this.entries.size === 0) return
|
|
868
|
+
const file = this.#canonicalFile(url)
|
|
869
|
+
assert.ok(this.entries.has(file), `Unknown entry point: ${file}`)
|
|
870
|
+
}
|
|
871
|
+
|
|
872
|
+
// The one preload (top-level) State, or undefined. Scans the process-wide registry
|
|
873
|
+
// (shared across stasis-core copies) for the member flagged isPreload.
|
|
874
|
+
static get preload() {
|
|
875
|
+
for (const state of liveStates()) if (state.isPreload) return state
|
|
876
|
+
return undefined
|
|
877
|
+
}
|
|
878
|
+
|
|
879
|
+
// True iff this is THE preload (top-level) State. Public so State.preload can identify
|
|
880
|
+
// it even when this State came from a different stasis-core copy.
|
|
881
|
+
get isPreload() {
|
|
882
|
+
return this.#isPreload
|
|
883
|
+
}
|
|
884
|
+
|
|
885
|
+
// The label under which this State claims `canonical` as a write target, or undefined.
|
|
886
|
+
// Public so #claimWritePath's collision scan can consult a State from another copy.
|
|
887
|
+
claimedWritePathLabel(canonical) {
|
|
888
|
+
return this.#claims.get(canonical)
|
|
889
|
+
}
|
|
890
|
+
|
|
891
|
+
// Claim a write target, refusing a path another live State (in ANY copy) already
|
|
892
|
+
// claims. Canonicalize so `./x` / `x` / symlinks compare equal. Scans the process-wide
|
|
893
|
+
// registry, so collisions are caught across copies and without a preload. Intra-State
|
|
894
|
+
// collisions are caught earlier by Config (#checkInvariants), so this only fires
|
|
895
|
+
// cross-State. The claim is recorded on this instance; it becomes visible to later
|
|
896
|
+
// States once this one is added to liveStates() at the end of construction.
|
|
897
|
+
#claimWritePath(label, value) {
|
|
898
|
+
if (!value) return
|
|
899
|
+
const canonical = canonicalizePath(value)
|
|
900
|
+
for (const other of liveStates()) {
|
|
901
|
+
const owner = other.claimedWritePathLabel(canonical)
|
|
902
|
+
assert.ok(owner === undefined, `${label} '${value}' is already claimed by ${owner} of another live State`)
|
|
903
|
+
}
|
|
904
|
+
this.#claims.set(canonical, label)
|
|
905
|
+
}
|
|
906
|
+
|
|
907
|
+
// This State's stasis-core version. Public so a child (sidecar) can verify it
|
|
908
|
+
// exactly matches its parent's even when the two are different module copies
|
|
909
|
+
// sharing the process-wide registry (see the constructor's parent branch).
|
|
910
|
+
get version() {
|
|
911
|
+
return VERSION
|
|
912
|
+
}
|
|
913
|
+
|
|
914
|
+
// The slice of parent state a child (sidecar) inherits. Exposed as a PUBLIC method
|
|
915
|
+
// (rather than the child reading the parent's private fields) so a sidecar from a
|
|
916
|
+
// different-but-version-matched stasis-core copy -- a bundle carrying its own
|
|
917
|
+
// stasis-core, whose plugin sidecars the outer loader's preload -- can read it across
|
|
918
|
+
// the class brand. Only ever called by the sidecar constructor, after its version
|
|
919
|
+
// assert; the exact-version match guarantees these shapes are compatible.
|
|
920
|
+
sidecarInheritance() {
|
|
921
|
+
return {
|
|
922
|
+
preloadRoot: this.#preloadRoot,
|
|
923
|
+
lockImports: this.#lockImports,
|
|
924
|
+
lockFormats: this.#lockFormats,
|
|
925
|
+
lockfileLoaded: this.#lockfileLoaded,
|
|
926
|
+
}
|
|
927
|
+
}
|
|
928
|
+
|
|
929
|
+
// Register a WRITE-mode child (sidecar) so this parent's unified lockData unions its
|
|
930
|
+
// imports/formats (and attestedBySidecar sees its captures). Public (not a direct
|
|
931
|
+
// `#sidecars.add`) for the same cross-copy reason as sidecarInheritance: the call runs
|
|
932
|
+
// on the parent, touching the parent's own #sidecars, so it works even when the sidecar
|
|
933
|
+
// is a foreign-copy instance.
|
|
934
|
+
registerSidecar(sidecar) {
|
|
935
|
+
this.#sidecars.add(sidecar)
|
|
936
|
+
}
|
|
937
|
+
|
|
938
|
+
// Register a LOAD-mode child as a read-only family member: getFs*Family serves bundle
|
|
939
|
+
// bytes from it (a --fs read at load of a file the sidecar carries) but, unlike
|
|
940
|
+
// registerSidecar, it never enters #mergedImports/#mergedFormats, so a load-mode sidecar
|
|
941
|
+
// contributes no resolution edges or formats (the lockfile's trust-bearing content) to the
|
|
942
|
+
// unified lockfile. Public for the same cross-copy reason as registerSidecar.
|
|
943
|
+
registerReadSidecar(sidecar) {
|
|
944
|
+
this.#readSidecars.add(sidecar)
|
|
945
|
+
}
|
|
946
|
+
|
|
947
|
+
absolute(url) {
|
|
948
|
+
const absolute = fileURLToPath(url)
|
|
949
|
+
assert.equal(pathToFileURL(absolute).toString(), url)
|
|
950
|
+
assert.equal(absolute, resolve(absolute))
|
|
951
|
+
return absolute
|
|
952
|
+
}
|
|
953
|
+
|
|
954
|
+
relative(absolute) {
|
|
955
|
+
assert.ok(absolute)
|
|
956
|
+
const file = relative(this.root, absolute)
|
|
957
|
+
assert.ok(!file.startsWith('..'))
|
|
958
|
+
return file
|
|
959
|
+
}
|
|
960
|
+
|
|
961
|
+
// A file reached under node_modules whose REAL path lies outside any
|
|
962
|
+
// node_modules is a workspace source linked into node_modules (pnpm links a
|
|
963
|
+
// workspace dependency in via a symlink). Canonicalize such a URL to its real
|
|
964
|
+
// path so it is recorded/looked up as a *source*, not a dependency -- and thus
|
|
965
|
+
// excluded from a node_modules-scope bundle. Everything else is returned
|
|
966
|
+
// untouched: plain sources, real dependencies, and node_modules -> node_modules
|
|
967
|
+
// links (e.g. pnpm's `.pnpm` store) keep their original path.
|
|
968
|
+
#canonical(url) {
|
|
969
|
+
const absolute = this.absolute(url)
|
|
970
|
+
const file = relative(this.root, absolute)
|
|
971
|
+
if (file.startsWith('..') || !splitNodeModulesPath(file)) return { url, absolute }
|
|
972
|
+
let real
|
|
973
|
+
try {
|
|
974
|
+
real = realpathSync(absolute)
|
|
975
|
+
} catch {
|
|
976
|
+
return { url, absolute }
|
|
977
|
+
}
|
|
978
|
+
if (real === absolute) return { url, absolute } // not a symlink
|
|
979
|
+
const realFile = relative(this.root, real)
|
|
980
|
+
// Outside the root, or still inside some node_modules (a real dependency,
|
|
981
|
+
// e.g. pnpm's `.pnpm` store): leave the recorded path unchanged.
|
|
982
|
+
if (realFile.startsWith('..') || splitNodeModulesPath(realFile)) return { url, absolute }
|
|
983
|
+
return { url: pathToFileURL(real).toString(), absolute: real }
|
|
984
|
+
}
|
|
985
|
+
|
|
986
|
+
// The canonical project-relative path a URL is recorded/looked up under.
|
|
987
|
+
#canonicalFile(url) {
|
|
988
|
+
return this.relative(this.#canonical(url).absolute)
|
|
989
|
+
}
|
|
990
|
+
|
|
991
|
+
// True when `url` resolves (through any workspace symlink) to a file under
|
|
992
|
+
// node_modules -- i.e. a bundled dependency -- as opposed to a workspace source
|
|
993
|
+
// linked into node_modules (which #canonical records as a source). The loader
|
|
994
|
+
// hooks gate on this rather than a raw `/node_modules/` substring, so a
|
|
995
|
+
// symlinked workspace source is read from disk / resolved by Node instead of
|
|
996
|
+
// being served from a node_modules-scope bundle that deliberately omits it.
|
|
997
|
+
// Tolerant: a URL it can't canonicalize (non-file, outside root) is treated as
|
|
998
|
+
// not-a-dependency, so the hook falls back to Node's default handling.
|
|
999
|
+
inNodeModules(url) {
|
|
1000
|
+
let file
|
|
1001
|
+
try {
|
|
1002
|
+
file = this.#canonicalFile(url)
|
|
1003
|
+
} catch {
|
|
1004
|
+
return false
|
|
1005
|
+
}
|
|
1006
|
+
return splitNodeModulesPath(file) !== null
|
|
1007
|
+
}
|
|
1008
|
+
|
|
1009
|
+
// Nearest package.json at or above a directory, for addFsDir (`stasis run --fs`
|
|
1010
|
+
// readdir captures). Replaces findPackageJSON, which is unreliable for a directory
|
|
1011
|
+
// URL (see #locateModule). Walks up using the real fs (the destructured existsSync
|
|
1012
|
+
// snapshot), bounded by the project root -- which is always an existing-package.json
|
|
1013
|
+
// dir, so an in-root directory always resolves. Returns an absolute package.json path.
|
|
1014
|
+
#nearestPackageJsonFor(dirAbsolute) {
|
|
1015
|
+
let dir = dirAbsolute
|
|
1016
|
+
while (true) {
|
|
1017
|
+
const candidate = join(dir, 'package.json')
|
|
1018
|
+
if (existsSync(candidate)) return candidate
|
|
1019
|
+
if (dir === this.root) break // checked the root's package.json; never escape root
|
|
1020
|
+
const parent = dirname(dir)
|
|
1021
|
+
if (parent === dir) break // filesystem root
|
|
1022
|
+
dir = parent
|
|
1023
|
+
}
|
|
1024
|
+
// Unreachable in practice: state.root is resolved to a dir that has package.json.
|
|
1025
|
+
assert.fail(`no package.json at or above directory ${this.relative(dirAbsolute)}`)
|
|
1026
|
+
}
|
|
1027
|
+
|
|
1028
|
+
// Canonicalize `url` and resolve the package bucket that owns it, registering the
|
|
1029
|
+
// module (name/version, `npm` ecosystem under node_modules) on first sight. Shared
|
|
1030
|
+
// by addFile (code/resource) and addFsDir (directory captures): everything here is
|
|
1031
|
+
// independent of a file's bytes or loader format, so both reuse it. Returns the
|
|
1032
|
+
// canonical absolute path, the project-relative `file`, the bucket `dir`/`module`,
|
|
1033
|
+
// and the nearest package `type` (for addFile's extension inference).
|
|
1034
|
+
//
|
|
1035
|
+
// `directory: true` (addFsDir): the url names a directory, not a file. Node's
|
|
1036
|
+
// findPackageJSON is unreliable for a directory URL -- depending on Node version
|
|
1037
|
+
// it returns the PARENT's package.json, `undefined` (at a bucket root), or even a
|
|
1038
|
+
// `node_modules/` DIRECTORY path, which readPackageJSON would then read as a file
|
|
1039
|
+
// and throw EISDIR. So for a directory we walk up to the nearest package.json
|
|
1040
|
+
// ourselves (#nearestPackageJsonFor), which is correct on every Node version.
|
|
1041
|
+
#locateModule(url, { directory = false } = {}) {
|
|
1042
|
+
// Canonicalize first: a workspace source linked into node_modules is recorded
|
|
1043
|
+
// under its real (non-node_modules) path so it classifies as a source.
|
|
1044
|
+
const canonical = this.#canonical(url)
|
|
1045
|
+
url = canonical.url
|
|
1046
|
+
const absolute = canonical.absolute
|
|
1047
|
+
assert.ok(existsSync(absolute))
|
|
1048
|
+
const file = this.relative(absolute)
|
|
1049
|
+
|
|
1050
|
+
const closestPkgAbsolute = directory ? this.#nearestPackageJsonFor(absolute) : findPackageJSON(url)
|
|
1051
|
+
const closestPkg = readPackageJSON(closestPkgAbsolute)
|
|
1052
|
+
|
|
1053
|
+
const closestType = closestPkg.type
|
|
1054
|
+
assert.ok(closestType === undefined || closestType === 'module' || closestType === 'commonjs')
|
|
1055
|
+
|
|
1056
|
+
// findPackageJSON may land on a `{"type":"module"}`-style sub-bucket
|
|
1057
|
+
// marker that lacks name/version.
|
|
1058
|
+
const nmRoot = splitNodeModulesPath(file)?.dir
|
|
1059
|
+
let pkgAbsolute, name, version
|
|
1060
|
+
if (nmRoot) {
|
|
1061
|
+
pkgAbsolute = resolve(this.root, nmRoot, 'package.json')
|
|
1062
|
+
const rootPkg = pkgAbsolute === closestPkgAbsolute ? closestPkg : readPackageJSON(pkgAbsolute)
|
|
1063
|
+
;({ name, version } = rootPkg)
|
|
1064
|
+
assert.ok(name, `Missing name in ${this.relative(pkgAbsolute)}`)
|
|
1065
|
+
assert.ok(version, `Missing version in ${this.relative(pkgAbsolute)}`)
|
|
1066
|
+
if (closestPkgAbsolute !== pkgAbsolute) {
|
|
1067
|
+
const message = `Inconsistent data between ${this.relative(closestPkgAbsolute)} and ${this.relative(pkgAbsolute)}`
|
|
1068
|
+
if (closestPkg.name !== undefined && closestPkg.name !== name) {
|
|
1069
|
+
// Allow fake module name subpaths: real module owns the prefix.
|
|
1070
|
+
// Npm publish wouldn't accept this anyway, so it's not a conflict.
|
|
1071
|
+
assert.ok(closestPkg.name.startsWith(`${name}/`), message)
|
|
1072
|
+
}
|
|
1073
|
+
|
|
1074
|
+
if (closestPkg.version !== undefined) assert.equal(closestPkg.version, version, message)
|
|
1075
|
+
}
|
|
1076
|
+
} else {
|
|
1077
|
+
pkgAbsolute = closestPkgAbsolute
|
|
1078
|
+
let json = closestPkg
|
|
1079
|
+
while (true) {
|
|
1080
|
+
if (json.name !== undefined && json.version !== undefined) {
|
|
1081
|
+
;({ name, version } = json)
|
|
1082
|
+
break
|
|
1083
|
+
}
|
|
1084
|
+
assert.ok(Object.keys(json).every((k) => k === 'type'))
|
|
1085
|
+
const next = findPackageJSON('..', pathToFileURL(pkgAbsolute))
|
|
1086
|
+
assert.ok(
|
|
1087
|
+
next && !relative(this.root, next).startsWith('..'),
|
|
1088
|
+
`No package.json with name+version found for ${file}`
|
|
1089
|
+
)
|
|
1090
|
+
pkgAbsolute = next
|
|
1091
|
+
json = readPackageJSON(pkgAbsolute)
|
|
1092
|
+
}
|
|
1093
|
+
}
|
|
1094
|
+
const pkg = this.relative(pkgAbsolute)
|
|
1095
|
+
assert.ok(pkg === 'package.json' || pkg.endsWith('/package.json'))
|
|
1096
|
+
assert.equal(basename(pkg), 'package.json')
|
|
1097
|
+
const dir = dirname(pkg)
|
|
1098
|
+
if (nmRoot) assert.equal(dir, nmRoot)
|
|
1099
|
+
if (!this.modules.has(dir)) {
|
|
1100
|
+
// node_modules buckets are installed dependencies; tag them with the `npm`
|
|
1101
|
+
// ecosystem so consumers can tell deps from the workspace's own packages
|
|
1102
|
+
// without re-deriving it from the path. Workspace/top-level buckets (the
|
|
1103
|
+
// scope=full `sources`) carry no ecosystem.
|
|
1104
|
+
this.modules.set(dir, nmRoot
|
|
1105
|
+
? { name, version, ecosystem: 'npm', files: Object.create(null) }
|
|
1106
|
+
: { name, version, files: Object.create(null) })
|
|
1107
|
+
}
|
|
1108
|
+
const module = this.modules.get(dir)
|
|
1109
|
+
assert.equal(module.name, name)
|
|
1110
|
+
assert.equal(module.version, version)
|
|
1111
|
+
|
|
1112
|
+
return { absolute, file, dir, module, closestType }
|
|
1113
|
+
}
|
|
1114
|
+
|
|
1115
|
+
// `resource: true` (alias: legacy `isBinary: true`) marks the file as a resource
|
|
1116
|
+
// rather than code. Its format is then derived from the bytes: 'resource' for valid
|
|
1117
|
+
// UTF-8 (stored raw, human-readable in the bundle) or 'resource:base64' for binary
|
|
1118
|
+
// (base64-encoded). Code files keep their inferred loader format.
|
|
1119
|
+
//
|
|
1120
|
+
// `inferFormat: false` records the bytes WITHOUT inferring or recording any loader
|
|
1121
|
+
// format (an existing recorded format, if any, is left intact). addFsFile uses it
|
|
1122
|
+
// for `.js`/`.ts`, whose module-vs-commonjs is Node's syntax-detection call (not
|
|
1123
|
+
// knowable from bytes): the module loader is the authority, so the fs-read capture
|
|
1124
|
+
// must not impose the legacy `commonjs` default and collide with a `module` the
|
|
1125
|
+
// loader records for the same file when it is both imported and read.
|
|
1126
|
+
addFile(url, { source, format, isEntry, isBinary, resource, inferFormat = true, reason = 'run', fsRead = false } = {}) {
|
|
1127
|
+
const asResource = resource === true || isBinary === true
|
|
1128
|
+
// A resource format must not arrive on the code path: 'resource' /
|
|
1129
|
+
// 'resource:base64' identifies asset payloads, which State stores in
|
|
1130
|
+
// `this.resources` with content-derived encoding (UTF-8 vs base64). A caller
|
|
1131
|
+
// who passes the format string without setting resource:true is asking for
|
|
1132
|
+
// a code file tagged as a resource -- nonsense, and exactly the kind of
|
|
1133
|
+
// accidental misclassification the per-file format design is meant to
|
|
1134
|
+
// catch. The reverse (resource:true with a non-resource format) is rejected
|
|
1135
|
+
// below when the content-derived format is checked against any explicit one.
|
|
1136
|
+
if (!asResource && Bundle.isResourceFormat(format)) {
|
|
1137
|
+
throw new Error(`addFile: format '${format}' requires resource: true`)
|
|
1138
|
+
}
|
|
1139
|
+
// A resource can't be an entry: entries name code loaded by Node (the module
|
|
1140
|
+
// graph's roots), and Bundle.parse / assertEntry validate them as code-shaped
|
|
1141
|
+
// paths. A resource entry would land in this.entries -> codeBundle.entries
|
|
1142
|
+
// (state.js's split-bundle getter), producing a v1 bundle whose entries refer
|
|
1143
|
+
// to files absent from its sources -- structurally valid but semantically
|
|
1144
|
+
// broken, and the kind of misclassification that's silent at capture time and
|
|
1145
|
+
// surfaces opaquely at the loader's NODEJS_FORMATS gate later.
|
|
1146
|
+
if (asResource && isEntry) {
|
|
1147
|
+
throw new Error(`addFile: a resource can't be an entry (resource:true + isEntry:true)`)
|
|
1148
|
+
}
|
|
1149
|
+
// Canonicalize + bucket by the owning package (shared with addFsDir).
|
|
1150
|
+
const { absolute, file, dir, module, closestType } = this.#locateModule(url)
|
|
1151
|
+
|
|
1152
|
+
// A code file can NEVER be recorded as a resource. `resources` -- the only gate
|
|
1153
|
+
// that admits an asset payload -- rejects code extensions outright (see
|
|
1154
|
+
// parseResourcesOption), so a resource:true call for a code extension means a
|
|
1155
|
+
// capture path bypassed that gate. That is exactly how an fs.readFileSync of a
|
|
1156
|
+
// `.jsx` got tagged 'resource', desyncing the unified lockfile (resource) from
|
|
1157
|
+
// the bundle (code) until it surfaced as an opaque format mismatch at load. Fail
|
|
1158
|
+
// at the recording site, where the cause is obvious, instead.
|
|
1159
|
+
if (asResource && CODE_EXTENSIONS.has(extname(file).slice(1).toLowerCase())) {
|
|
1160
|
+
throw new Error(`addFile: a code file can't be recorded as a resource: ${file}`)
|
|
1161
|
+
}
|
|
1162
|
+
|
|
1163
|
+
// Resources don't get a loader format inferred from extension/package type --
|
|
1164
|
+
// their format ('resource' / 'resource:base64') is chosen by content below.
|
|
1165
|
+
// inferFormat:false (addFsFile for .js/.ts) skips inference entirely.
|
|
1166
|
+
if (!asResource && inferFormat) {
|
|
1167
|
+
const extToFormat = {
|
|
1168
|
+
__proto__: null,
|
|
1169
|
+
'.json': 'json',
|
|
1170
|
+
'.mjs': 'module',
|
|
1171
|
+
'.cjs': 'commonjs',
|
|
1172
|
+
'.mts': 'module-typescript',
|
|
1173
|
+
'.cts': 'commonjs-typescript',
|
|
1174
|
+
}
|
|
1175
|
+
if (closestType !== undefined) {
|
|
1176
|
+
extToFormat['.js'] = closestType
|
|
1177
|
+
extToFormat['.ts'] = `${closestType}-typescript`
|
|
1178
|
+
}
|
|
1179
|
+
const inferredFormat = extToFormat[extname(file)]
|
|
1180
|
+
if (inferredFormat !== undefined) {
|
|
1181
|
+
if (format != null) assert.equal(format, inferredFormat)
|
|
1182
|
+
else format = inferredFormat
|
|
1183
|
+
} else if (format == null) {
|
|
1184
|
+
// No `type` in the nearest package.json: Node decides .js/.ts by
|
|
1185
|
+
// module-syntax detection, so either variant is legitimate and the
|
|
1186
|
+
// caller's reported format wins. When no format was provided at all
|
|
1187
|
+
// (e.g. bundler plugins, whose afterResolve/onLoad pass none), defer to
|
|
1188
|
+
// a format already recorded for this file THIS session before falling
|
|
1189
|
+
// back to the legacy commonjs default. The runtime loader records Node's
|
|
1190
|
+
// authoritative module/commonjs choice (hooks.js's load hook), so a
|
|
1191
|
+
// later no-format capture of the same file must KEEP a known `module`
|
|
1192
|
+
// rather than re-default it to commonjs -- which would both mis-attest
|
|
1193
|
+
// the bundle and collide at the noupsert below (and, for a bundler
|
|
1194
|
+
// sidecar whose formats merge into the parent's unified lockfile, at
|
|
1195
|
+
// #mergedFormats). A sidecar's loader records land in the parent's
|
|
1196
|
+
// formats, so consult it too. Only an extension-appropriate code format
|
|
1197
|
+
// is reused; a stale resource tag from a conflicting prior capture falls
|
|
1198
|
+
// through to the default so the conflict still surfaces at noupsert.
|
|
1199
|
+
const variants = {
|
|
1200
|
+
__proto__: null,
|
|
1201
|
+
'.js': ['commonjs', 'module'],
|
|
1202
|
+
'.ts': ['commonjs-typescript', 'module-typescript'],
|
|
1203
|
+
}[extname(file)]
|
|
1204
|
+
const known = this.formats.get(file) ?? this.#parent?.formats.get(file)
|
|
1205
|
+
format = variants?.includes(known) ? known : variants?.[0]
|
|
1206
|
+
}
|
|
1207
|
+
}
|
|
1208
|
+
|
|
1209
|
+
let sourceFromDisk = false
|
|
1210
|
+
if (typeof source === 'string') {
|
|
1211
|
+
assert.ok(source.isWellFormed())
|
|
1212
|
+
} else {
|
|
1213
|
+
if (source === undefined || source === null) { source = readFileSync(absolute); sourceFromDisk = true }
|
|
1214
|
+
assert.ok(Buffer.isBuffer(source))
|
|
1215
|
+
if (!asResource) assert.ok(isUtf8(source), `File is not UTF-8: ${file}`)
|
|
1216
|
+
}
|
|
1217
|
+
|
|
1218
|
+
const buf = typeof source === 'string' ? Buffer.from(source) : source
|
|
1219
|
+
// Verify a CALLER-PROVIDED source against disk (the loader passes the bytes it is about to
|
|
1220
|
+
// execute; this catches a loader serving bytes that differ from the file on disk). When we
|
|
1221
|
+
// just read `source` from disk ourselves, that comparison is against the same read -- it is
|
|
1222
|
+
// tautological -- so skip the redundant second read.
|
|
1223
|
+
if (!sourceFromDisk) assert.deepStrictEqual(readFileSync(absolute), buf)
|
|
1224
|
+
|
|
1225
|
+
// Resource format is content-driven: raw UTF-8 stays 'resource' (don't base64
|
|
1226
|
+
// bytes that are already text); anything else is 'resource:base64'.
|
|
1227
|
+
if (asResource) {
|
|
1228
|
+
const derived = isUtf8(buf) ? 'resource' : 'resource:base64'
|
|
1229
|
+
if (format != null) assert.equal(format, derived, `resource format mismatch for ${file}`)
|
|
1230
|
+
format = derived
|
|
1231
|
+
}
|
|
1232
|
+
|
|
1233
|
+
if (isEntry) this.entries.add(file)
|
|
1234
|
+
const integrity = sha512integrity(source)
|
|
1235
|
+
noupsert(this.hashes, file, integrity)
|
|
1236
|
+
if (this.config.childProcess) this.#observed.add(file) // only a child's shardSnapshot reads it; skip when the channel is off
|
|
1237
|
+
if (this.config.bundle && reason !== null) {
|
|
1238
|
+
this.#recordReason(reason, file) // provenance for the bundle's `reason` field (null = not a consumer observation, e.g. backfill)
|
|
1239
|
+
// Track HOW 'run' saw this file so #bundleReason can drop files run merely fs-READ after a
|
|
1240
|
+
// plugin attached that a plugin actually bundles (e.g. webpack+babel reading app source).
|
|
1241
|
+
if (reason === 'run') {
|
|
1242
|
+
if (!fsRead) this.#runImported.add(file)
|
|
1243
|
+
else if (this.#pluginAttached) this.#fsReadPostPlugin.add(file)
|
|
1244
|
+
}
|
|
1245
|
+
}
|
|
1246
|
+
const rel = relative(dir, file)
|
|
1247
|
+
assert.ok(!rel.startsWith('..'))
|
|
1248
|
+
|
|
1249
|
+
const inAttestedZone = dir.includes('node_modules') || this.config.full
|
|
1250
|
+
if (this.config.frozen && inAttestedZone) {
|
|
1251
|
+
assert.ok(Object.hasOwn(module.files, rel))
|
|
1252
|
+
}
|
|
1253
|
+
|
|
1254
|
+
// Frozen bundle: the observed bytes are checked against the bundle by the
|
|
1255
|
+
// noupsert into this.sources/this.resources below (both pre-seeded from the
|
|
1256
|
+
// bundle); here we close the set, rejecting a file the bundle never recorded
|
|
1257
|
+
// (mirrors the lockfile membership check above, anchored in the bundle). The
|
|
1258
|
+
// scope carve-out matches the lockfile's: node_modules scope doesn't attest
|
|
1259
|
+
// workspace files, so they aren't required to be in the bundle.
|
|
1260
|
+
if (this.config.frozenBundle && inAttestedZone) {
|
|
1261
|
+
const attested = asResource ? this.#bundleResources : this.#bundleSources
|
|
1262
|
+
assert.ok(attested?.has(file), `File not attested by the frozen bundle: ${file}`)
|
|
1263
|
+
}
|
|
1264
|
+
|
|
1265
|
+
// Frozen runs verify the format observed on disk against the attestation, the
|
|
1266
|
+
// way addImport verifies resolutions: the on-disk format is derived from the
|
|
1267
|
+
// file extension + nearest package.json `type`, and `type` is usually not
|
|
1268
|
+
// itself hash-attested, so flipping it recategorizes a hash-valid file
|
|
1269
|
+
// (commonjs<->module, or .js<->module-typescript) with no hash mismatch.
|
|
1270
|
+
// Checked against the lockfile and/or the frozen bundle, each anchored in its
|
|
1271
|
+
// own recorded formats. Gated to the same attested zone as the hash check
|
|
1272
|
+
// above (the node_modules-scope workspace is deliberately unattested, like
|
|
1273
|
+
// its bytes); files with no derived format (binary resources) are skipped via
|
|
1274
|
+
// `format != null`.
|
|
1275
|
+
if (this.config.frozen && this.#lockFormats !== null && format != null && inAttestedZone) {
|
|
1276
|
+
this.#assertAttestedFormat(this.#lockFormats, file, format, { what: 'observed', source: 'lockfile' })
|
|
1277
|
+
}
|
|
1278
|
+
if (this.config.frozenBundle && this.#bundleFormats !== null && format != null && inAttestedZone) {
|
|
1279
|
+
this.#assertAttestedFormat(this.#bundleFormats, file, format, { what: 'observed', source: 'frozen bundle' })
|
|
1280
|
+
}
|
|
1281
|
+
|
|
1282
|
+
// A WRITING lock capture (lock=add) must catch a format flip on already-attested bytes EARLY.
|
|
1283
|
+
// The lockfile baseline lives in #lockFormats -- separate from this.formats -- so addFile's own
|
|
1284
|
+
// noupsert below won't see the clash; it would otherwise surface only later at write(), when
|
|
1285
|
+
// #mergedFormats unions the baseline with the session formats and noupsert throws a bare
|
|
1286
|
+
// `Conflict for <file>` with no cause or remedy. Detect it here and throw a clear, actionable
|
|
1287
|
+
// error instead. (A frozen run rejects it via the format check above; lock=replace discards the
|
|
1288
|
+
// baseline, so #lockFormats is null; and bundle=add seeds the bundle's formats into this.formats,
|
|
1289
|
+
// so a bundle-side flip already conflicts at the noupsert below. Re-attest a genuine change with
|
|
1290
|
+
// --lock=replace / --bundle=replace.)
|
|
1291
|
+
if (this.config.writeLockfile && this.#lockFormats !== null && format != null && inAttestedZone) {
|
|
1292
|
+
const attested = this.#lockFormats.get(file)
|
|
1293
|
+
assert.ok(attested === undefined || attested === format,
|
|
1294
|
+
`format flip for ${file}: lockfile attests '${attested}', observed '${format}' (bytes unchanged) -- re-run with --lock=replace to re-attest`)
|
|
1295
|
+
}
|
|
1296
|
+
|
|
1297
|
+
if (!Object.hasOwn(module.files, rel)) module.files[rel] = integrity
|
|
1298
|
+
assert.equal(module.files[rel], integrity)
|
|
1299
|
+
|
|
1300
|
+
if (this.config.bundle) {
|
|
1301
|
+
if (asResource) {
|
|
1302
|
+
// 'resource' stores the raw UTF-8 string; 'resource:base64' stores base64.
|
|
1303
|
+
const content = format === 'resource:base64' ? buf.toString('base64') : buf.toString('utf8')
|
|
1304
|
+
noupsert(this.resources, file, content)
|
|
1305
|
+
} else {
|
|
1306
|
+
noupsert(this.sources, file, typeof source === 'string' ? source : source.toString())
|
|
1307
|
+
}
|
|
1308
|
+
}
|
|
1309
|
+
|
|
1310
|
+
if (format) noupsert(this.formats, file, format)
|
|
1311
|
+
}
|
|
1312
|
+
|
|
1313
|
+
// Record an `fs.readFileSync` capture (`stasis run --fs`, capture side). `source` is
|
|
1314
|
+
// the raw bytes (a Buffer). Classification is the SAME classifyExtension the bundler
|
|
1315
|
+
// plugins use (against this.config.resources), so the two capture paths can't disagree:
|
|
1316
|
+
// - 'code' (any CODE_EXTENSIONS file) → addFile infers the Node loader format from the
|
|
1317
|
+
// extension. .js/.ts defer it (inferFormat:false): module-vs-commonjs is Node's
|
|
1318
|
+
// syntax-detection call, the loader is the authority, and forcing a default here
|
|
1319
|
+
// would collide (noupsert) with the loader's record when a file is both imported and
|
|
1320
|
+
// fs-read. .jsx/.tsx are code but have no Node loader format, so none is imposed.
|
|
1321
|
+
// addFile asserts the bytes are UTF-8 -- a non-UTF-8 code file is malformed input,
|
|
1322
|
+
// refused there rather than silently re-tagged as a resource.
|
|
1323
|
+
// - 'resource' (an extension in the resources allowlist) → a 'resource'/'resource:base64'
|
|
1324
|
+
// payload, encoding chosen from the bytes.
|
|
1325
|
+
// - 'unknown' (neither code nor an allowlisted resource) → THROW. Recording it as a
|
|
1326
|
+
// resource would silently widen the attested set (the exact desync this guards); the
|
|
1327
|
+
// --fs hook catches the throw, warns, and writes nothing. Declare the extension in
|
|
1328
|
+
// `resources` (the --resources flag / EXODUS_STASIS_RESOURCES / a plugin's resources
|
|
1329
|
+
// option) or stop reading it.
|
|
1330
|
+
// Routing through addFile means a file that is BOTH imported and fs-read lands in one
|
|
1331
|
+
// consistent, deduped entry, hashed and bucketed exactly like every other file.
|
|
1332
|
+
addFsFile(url, source) {
|
|
1333
|
+
assert.ok(Buffer.isBuffer(source), 'addFsFile requires a Buffer source')
|
|
1334
|
+
const path = fileURLToPath(url)
|
|
1335
|
+
const kind = classifyExtension(path, this.config.resources)
|
|
1336
|
+
if (kind === 'resource') {
|
|
1337
|
+
this.addFile(url, { source, resource: true, fsRead: true })
|
|
1338
|
+
return
|
|
1339
|
+
}
|
|
1340
|
+
const ext = extname(path).toLowerCase()
|
|
1341
|
+
if (kind === 'unknown') {
|
|
1342
|
+
throw new Error(
|
|
1343
|
+
`addFsFile: ${path} is neither code nor a declared resource; ` +
|
|
1344
|
+
`add its extension or filename to the resources allowlist or stop reading it`
|
|
1345
|
+
)
|
|
1346
|
+
}
|
|
1347
|
+
this.addFile(url, { source, inferFormat: ext !== '.js' && ext !== '.ts', fsRead: true })
|
|
1348
|
+
}
|
|
1349
|
+
|
|
1350
|
+
// Record an `fs.readdirSync(path)` capture (single-arg form only). The listing is
|
|
1351
|
+
// SORTED so the attested content is reproducible regardless of the OS's directory
|
|
1352
|
+
// order, JSON-serialized, and stored as a 'directory'-format payload -- a
|
|
1353
|
+
// resource-like file whose integrity (sha512 over the JSON text) lands in the
|
|
1354
|
+
// lockfile just like any other content. Buckets/dedups via #locateModule like
|
|
1355
|
+
// addFile; the directory's own project-relative path is the key (a readdir of a
|
|
1356
|
+
// module root keys the listing at the bucket itself -- see moduleFileKey).
|
|
1357
|
+
addFsDir(url, names) {
|
|
1358
|
+
assert.ok(Array.isArray(names) && names.every((n) => typeof n === 'string'),
|
|
1359
|
+
'addFsDir requires an array of string names')
|
|
1360
|
+
const { file, dir, module } = this.#locateModule(url, { directory: true })
|
|
1361
|
+
const content = JSON.stringify(names.toSorted())
|
|
1362
|
+
const format = 'directory'
|
|
1363
|
+
const integrity = sha512integrity(content)
|
|
1364
|
+
noupsert(this.hashes, file, integrity)
|
|
1365
|
+
if (this.config.childProcess) this.#observed.add(file) // only a child's shardSnapshot reads it; skip when the channel is off
|
|
1366
|
+
// Directory captures come only from the loader's --fs, and a plugin never records a readdir
|
|
1367
|
+
// listing (plugins only addFile), so a directory key is never in #bundleReason's pluginFiles
|
|
1368
|
+
// and can never be dropped from 'run' -- no need to track it in #fsReadPostPlugin.
|
|
1369
|
+
if (this.config.bundle) this.#recordReason('run', file)
|
|
1370
|
+
const rel = relative(dir, file)
|
|
1371
|
+
assert.ok(!rel.startsWith('..'))
|
|
1372
|
+
|
|
1373
|
+
// Frozen attestation, mirroring addFile: in the attested zone the listing must
|
|
1374
|
+
// already be recorded (closed set) and its format/integrity must match.
|
|
1375
|
+
const inAttestedZone = dir.includes('node_modules') || this.config.full
|
|
1376
|
+
if (this.config.frozen && inAttestedZone) {
|
|
1377
|
+
assert.ok(Object.hasOwn(module.files, rel))
|
|
1378
|
+
}
|
|
1379
|
+
if (this.config.frozenBundle && inAttestedZone) {
|
|
1380
|
+
assert.ok(this.#bundleResources?.has(file), `Directory not attested by the frozen bundle: ${file}`)
|
|
1381
|
+
}
|
|
1382
|
+
if (this.config.frozen && this.#lockFormats !== null && inAttestedZone) {
|
|
1383
|
+
this.#assertAttestedFormat(this.#lockFormats, file, format, { what: 'observed', source: 'lockfile' })
|
|
1384
|
+
}
|
|
1385
|
+
if (this.config.frozenBundle && this.#bundleFormats !== null && inAttestedZone) {
|
|
1386
|
+
this.#assertAttestedFormat(this.#bundleFormats, file, format, { what: 'observed', source: 'frozen bundle' })
|
|
1387
|
+
}
|
|
1388
|
+
|
|
1389
|
+
if (!Object.hasOwn(module.files, rel)) module.files[rel] = integrity
|
|
1390
|
+
assert.equal(module.files[rel], integrity)
|
|
1391
|
+
if (this.config.bundle) noupsert(this.resources, file, content)
|
|
1392
|
+
noupsert(this.formats, file, format)
|
|
1393
|
+
}
|
|
1394
|
+
|
|
1395
|
+
// Serve an `fs.readFileSync` from the bundle (`stasis run --fs`, bundle=load).
|
|
1396
|
+
// Returns the raw bytes as a Buffer, or undefined when the path was not captured
|
|
1397
|
+
// (the hook then falls back to a real disk read) or names a captured directory (a
|
|
1398
|
+
// readFileSync of a directory must fail, not return its listing). Decoding and the
|
|
1399
|
+
// lockfile hash check reuse getFile. Note a captured `.js`/`.ts` may have no
|
|
1400
|
+
// recorded format (see addFsFile); it's still served from `this.sources` by
|
|
1401
|
+
// presence -- the format only governs the module loader, not an fs read.
|
|
1402
|
+
getFsFile(url) {
|
|
1403
|
+
let file
|
|
1404
|
+
try { file = this.#canonicalFile(url) } catch { return undefined }
|
|
1405
|
+
if (this.formats.get(file) === 'directory') return undefined
|
|
1406
|
+
if (!this.sources.has(file) && !this.resources.has(file)) return undefined
|
|
1407
|
+
const { source } = this.getFile(url)
|
|
1408
|
+
return Buffer.isBuffer(source) ? source : Buffer.from(source, 'utf8')
|
|
1409
|
+
}
|
|
1410
|
+
|
|
1411
|
+
// Serve an `fs.readdirSync(path)` from the bundle: the sorted listing captured at
|
|
1412
|
+
// build time, or undefined when the path was not captured as a directory (the hook
|
|
1413
|
+
// falls back to a real disk read). Reuses getFile for the hash check.
|
|
1414
|
+
getFsDir(url) {
|
|
1415
|
+
let file
|
|
1416
|
+
try { file = this.#canonicalFile(url) } catch { return undefined }
|
|
1417
|
+
if (this.formats.get(file) !== 'directory') return undefined
|
|
1418
|
+
const { source } = this.getFile(url)
|
|
1419
|
+
const names = JSON.parse(source)
|
|
1420
|
+
assert.ok(Array.isArray(names), `corrupt directory listing for ${file}`)
|
|
1421
|
+
return names
|
|
1422
|
+
}
|
|
1423
|
+
|
|
1424
|
+
// Every ancestor directory implied by the bundle's recorded file/resource/directory
|
|
1425
|
+
// 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).
|
|
1427
|
+
#impliedDirs() {
|
|
1428
|
+
if (this.#impliedDirIndex) return this.#impliedDirIndex
|
|
1429
|
+
const dirs = new Set([''])
|
|
1430
|
+
const add = (key) => {
|
|
1431
|
+
let prefix = ''
|
|
1432
|
+
const parts = key.split('/')
|
|
1433
|
+
for (let i = 0; i < parts.length - 1; i++) {
|
|
1434
|
+
prefix = prefix === '' ? parts[i] : `${prefix}/${parts[i]}`
|
|
1435
|
+
dirs.add(prefix)
|
|
1436
|
+
}
|
|
1437
|
+
}
|
|
1438
|
+
for (const key of this.sources.keys()) add(key)
|
|
1439
|
+
for (const key of this.resources.keys()) add(key)
|
|
1440
|
+
this.#impliedDirIndex = dirs
|
|
1441
|
+
return dirs
|
|
1442
|
+
}
|
|
1443
|
+
|
|
1444
|
+
// Classify a captured path for the `fs.lstatSync(x)/statSync(x)` .isFile()/.isDirectory()
|
|
1445
|
+
// 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.
|
|
1451
|
+
getFsStat(url) {
|
|
1452
|
+
let file
|
|
1453
|
+
try { file = this.#canonicalFile(url) } catch { return undefined }
|
|
1454
|
+
if (this.formats.get(file) === 'directory') return 'directory'
|
|
1455
|
+
if (this.sources.has(file) || this.resources.has(file)) return 'file'
|
|
1456
|
+
if (this.#impliedDirs().has(file)) return 'directory'
|
|
1457
|
+
return undefined
|
|
1458
|
+
}
|
|
1459
|
+
|
|
1460
|
+
// --fs <-> bundler-plugin coordination. A StasisWebpack/StasisEsbuild/StasisMetro SIDECAR
|
|
1461
|
+
// (its own bundleFile) captures the bundler's MODULE GRAPH into its OWN bundle. But the
|
|
1462
|
+
// bundler also reads every module's source through node:fs (webpack's inputFileSystem is
|
|
1463
|
+
// graceful-fs -> node:fs), which the --fs hook would otherwise RE-record into THIS
|
|
1464
|
+
// (preload/"main") bundle -- copying the whole graph into main and defeating the
|
|
1465
|
+
// bundleFile split. So --fs consults the family in two symmetric ways:
|
|
1466
|
+
// - CAPTURE (write mode): attestedBySidecar SKIPS recording a read a write-mode sidecar
|
|
1467
|
+
// already attests (the graph). Only reads no sidecar owns -- a babel plugin's manual
|
|
1468
|
+
// non-JS file reads, etc. -- are recorded into main.
|
|
1469
|
+
// - LOAD (load mode): getFs*Family SERVES a graph file from a load-mode sidecar's bundle
|
|
1470
|
+
// when main doesn't carry it (a program raw-reading a graph file via --fs at load).
|
|
1471
|
+
// The two paths consult DIFFERENT registries because a sidecar is a contributor XOR a
|
|
1472
|
+
// consumer (its bundle mode is the parent's): write-mode sidecars (#sidecars) feed the
|
|
1473
|
+
// lockfile; load-mode sidecars (#readSidecars) must not. readdir capture has no skip --
|
|
1474
|
+
// bundler plugins record files (addFile), never directory LISTINGS (addFsDir), so a
|
|
1475
|
+
// sidecar never owns a readdir result; a readdir is a genuine program read for main.
|
|
1476
|
+
//
|
|
1477
|
+
// attestedBySidecar consults #sidecars (write-mode contributors) and excludes THIS State
|
|
1478
|
+
// on purpose: a file only this State has stays subject to --fs's own dedup / byte-conflict
|
|
1479
|
+
// detection (addFsFile's noupsert); the skip applies solely to a file a *sidecar* carries.
|
|
1480
|
+
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
|
|
1486
|
+
return false
|
|
1487
|
+
}
|
|
1488
|
+
|
|
1489
|
+
// getFs* variants that also consult load-mode sidecars (#readSidecars; this State first),
|
|
1490
|
+
// so a file/dir a sidecar carries in its bundle is served by --fs reads at load even when
|
|
1491
|
+
// main doesn't carry it. Only #readSidecars (not #sidecars): write-mode sidecars exist
|
|
1492
|
+
// only during capture, where --fs records rather than serves, so they're never consulted
|
|
1493
|
+
// here -- and they're kept out of the lockfile-contributing path regardless.
|
|
1494
|
+
getFsFileFamily(url) {
|
|
1495
|
+
const own = this.getFsFile(url)
|
|
1496
|
+
if (own !== undefined) return own
|
|
1497
|
+
for (const s of this.#readSidecars) { const v = s.getFsFile(url); if (v !== undefined) return v }
|
|
1498
|
+
return undefined
|
|
1499
|
+
}
|
|
1500
|
+
|
|
1501
|
+
getFsStatFamily(url) {
|
|
1502
|
+
const own = this.getFsStat(url)
|
|
1503
|
+
if (own !== undefined) return own
|
|
1504
|
+
for (const s of this.#readSidecars) { const v = s.getFsStat(url); if (v !== undefined) return v }
|
|
1505
|
+
return undefined
|
|
1506
|
+
}
|
|
1507
|
+
|
|
1508
|
+
getFsDirFamily(url) {
|
|
1509
|
+
const own = this.getFsDir(url)
|
|
1510
|
+
if (own !== undefined) return own
|
|
1511
|
+
// The sidecar loop is inert in practice: bundler plugins record files (addFile), never
|
|
1512
|
+
// directory LISTINGS (addFsDir), so a sidecar's bundle has no `directory` entry and
|
|
1513
|
+
// s.getFsDir always returns undefined. Kept for symmetry with the file/stat families.
|
|
1514
|
+
for (const s of this.#readSidecars) { const v = s.getFsDir(url); if (v !== undefined) return v }
|
|
1515
|
+
return undefined
|
|
1516
|
+
}
|
|
1517
|
+
|
|
1518
|
+
getFile(url) {
|
|
1519
|
+
// #canonicalFile -> relative() throws a bare assertion if the URL is outside
|
|
1520
|
+
// state.root (an absolute path that escapes the project). Wrap it so callers
|
|
1521
|
+
// get a contextual message instead of a stack pointing at relative()'s
|
|
1522
|
+
// assert.ok(!file.startsWith('..')).
|
|
1523
|
+
let file
|
|
1524
|
+
try { file = this.#canonicalFile(url) }
|
|
1525
|
+
catch (cause) { throw new Error(`stasis: file is outside the project root: ${url}`, { cause }) }
|
|
1526
|
+
const format = this.formats.get(file) // might be undefined e.g. for some bundlers
|
|
1527
|
+
// Resources live in this.resources, code in this.sources. Decode per the format:
|
|
1528
|
+
// 'resource:base64' is base64, 'resource' is raw UTF-8, code is raw text.
|
|
1529
|
+
// A missing entry throws with the URL in context so load-mode callers (the
|
|
1530
|
+
// bundler plugins, the run loader) don't have to pre-check existence -- the
|
|
1531
|
+
// single getFile call is the fail-closed gate.
|
|
1532
|
+
let source
|
|
1533
|
+
if (Bundle.isResourceFormat(format)) {
|
|
1534
|
+
source = this.resources.get(file)
|
|
1535
|
+
if (source === undefined) throw new Error(`stasis: file not attested in bundle: ${url}`)
|
|
1536
|
+
if (format === 'resource:base64') source = Buffer.from(source, 'base64')
|
|
1537
|
+
} else {
|
|
1538
|
+
source = this.sources.get(file)
|
|
1539
|
+
if (source === undefined) throw new Error(`stasis: file not attested in bundle: ${url}`)
|
|
1540
|
+
}
|
|
1541
|
+
// Without a lockfile the bundle is self-attesting: hashes would be derived
|
|
1542
|
+
// from the same source bytes we'd then verify, which is a tautology.
|
|
1543
|
+
if (this.config.useLockfile) assert.equal(this.hashes.get(file), sha512integrity(source))
|
|
1544
|
+
return { source, format }
|
|
1545
|
+
}
|
|
1546
|
+
|
|
1547
|
+
getFormat(url) {
|
|
1548
|
+
return this.formats.get(this.#canonicalFile(url))
|
|
1549
|
+
}
|
|
1550
|
+
|
|
1551
|
+
// Different conditions / import attributes can yield different URLs/formats for the same parent+specifier
|
|
1552
|
+
#conditionsKey(conditions, importAttributes) {
|
|
1553
|
+
const cond = conditions === '*' ? '*' : conditions.join(', ')
|
|
1554
|
+
assert.ok(!cond.includes('(') && !cond.includes(')'), 'conditions must not contain "(" or ")"')
|
|
1555
|
+
const attrs = importAttributes ? Object.entries(importAttributes) : []
|
|
1556
|
+
if (attrs.length === 0) return cond
|
|
1557
|
+
const sorted = Object.fromEntries(attrs.toSorted(([a], [b]) => (a < b ? -1 : 1)))
|
|
1558
|
+
return `${cond} (with: ${JSON.stringify(sorted)})`
|
|
1559
|
+
}
|
|
1560
|
+
|
|
1561
|
+
// A require()/import() given an already-resolved ABSOLUTE path arrives at the
|
|
1562
|
+
// resolve hook with that absolute path AS the specifier -- CJS
|
|
1563
|
+
// `require('/repo/node_modules/pkg/index.js')` is the common case (webpack's
|
|
1564
|
+
// loader-runner does `require(loader.path)`). Recorded verbatim, that
|
|
1565
|
+
// machine-specific absolute path becomes a resolution KEY in the lockfile and
|
|
1566
|
+
// bundle: non-portable, and unmatchable on any other machine. Once the target
|
|
1567
|
+
// is confirmed inside the project root, renormalize it to a path relative to
|
|
1568
|
+
// the IMPORTING FILE's directory -- the same shape a hand-written
|
|
1569
|
+
// `require('./x')` / `require('../../pkg/x')` has. The root check is only the
|
|
1570
|
+
// gate; the resulting key may itself contain '../' (going up from the importing
|
|
1571
|
+
// file), which is expected and fine as long as the target stayed inside root.
|
|
1572
|
+
//
|
|
1573
|
+
// Keying against the parent makes the key portable AND collision-free: it is
|
|
1574
|
+
// always '.'-prefixed, so it can never clash with a bare ('pkg') or
|
|
1575
|
+
// root-relative key, and an absolute path naming the same file as a relative
|
|
1576
|
+
// import unifies onto the identical key (same value -> noupsert agrees, no
|
|
1577
|
+
// throw). Bare/relative specifiers and file: URLs (handled separately by the
|
|
1578
|
+
// loader) pass through untouched; an absolute path that escapes the root has no
|
|
1579
|
+
// in-root relative form, so it's left as-is. Applied identically in addImport
|
|
1580
|
+
// (record) and getImport (lookup) so the key written and the key queried agree.
|
|
1581
|
+
#canonicalSpecifier(parentURL, specifier) {
|
|
1582
|
+
if (typeof specifier !== 'string' || !isAbsolute(specifier)) return specifier
|
|
1583
|
+
const fromRoot = relative(this.root, specifier)
|
|
1584
|
+
if (fromRoot === '' || fromRoot.startsWith('..')) return specifier // outside the project root
|
|
1585
|
+
const rel = relative(dirname(fileURLToPath(parentURL)), specifier)
|
|
1586
|
+
return rel.startsWith('.') ? rel : `./${rel}`
|
|
1587
|
+
}
|
|
1588
|
+
|
|
1589
|
+
addImport(parentURL, specifier, url, { conditions = '*', format, importAttributes } = {}) {
|
|
1590
|
+
if (conditions !== '*') assert.ok(Array.isArray(conditions))
|
|
1591
|
+
// Capture Node's require-condition set the first time we see a require()-context
|
|
1592
|
+
// edge: it carries 'require' and never 'import' (the import set carries 'import'
|
|
1593
|
+
// instead). Requiring the absence of 'import' also rejects an import edge a user
|
|
1594
|
+
// forced 'require' onto via --conditions. #backfillObservedResolutions reuses this
|
|
1595
|
+
// set to key native require.resolve() edges accurately instead of '*' (see field doc).
|
|
1596
|
+
if (this.#requireConditions === null && Array.isArray(conditions) &&
|
|
1597
|
+
conditions.includes('require') && !conditions.includes('import')) {
|
|
1598
|
+
this.#requireConditions = conditions
|
|
1599
|
+
}
|
|
1600
|
+
assert.ok(parentURL, 'addImport requires a parent (entries go through addFile)')
|
|
1601
|
+
const parent = this.#canonicalFile(parentURL)
|
|
1602
|
+
const file = this.#canonicalFile(url)
|
|
1603
|
+
specifier = this.#canonicalSpecifier(parentURL, specifier)
|
|
1604
|
+
const key = this.#conditionsKey(conditions, importAttributes)
|
|
1605
|
+
|
|
1606
|
+
// Frozen runs verify resolutions observed from disk against the lockfile,
|
|
1607
|
+
// mirroring the bundle-side check: byte hashes can't see a resolution
|
|
1608
|
+
// redirected to a *different* attested file (e.g. via an unattested
|
|
1609
|
+
// package.json `main` or a symlink). An edge the lockfile attests must
|
|
1610
|
+
// match in every scope. Unknown edges are fatal in full scope (the
|
|
1611
|
+
// attested file set is closed, so the traversed edge set should be too),
|
|
1612
|
+
// but tolerated for workspace parents in node_modules scope -- the
|
|
1613
|
+
// workspace is deliberately unattested there, so changed workspace code
|
|
1614
|
+
// may legitimately introduce new edges, including into pinned packages.
|
|
1615
|
+
const tolerateUnknown = !this.config.full && !parent.includes('node_modules')
|
|
1616
|
+
if (this.config.frozen && this.#lockImports !== null) {
|
|
1617
|
+
this.#assertAttestedResolution(this.#lockImports, key, parent, specifier, file, { what: 'observed', source: 'lockfile', tolerateUnknown })
|
|
1618
|
+
}
|
|
1619
|
+
// A frozen bundle attests resolutions the same way (every v1 bundle carries an
|
|
1620
|
+
// `imports` map, so #bundleImports is never null once one is loaded). Same
|
|
1621
|
+
// redirect protection and node_modules-scope carve-out, anchored in the bundle.
|
|
1622
|
+
if (this.config.frozenBundle && this.#bundleImports !== null) {
|
|
1623
|
+
this.#assertAttestedResolution(this.#bundleImports, key, parent, specifier, file, { what: 'observed', source: 'frozen bundle', tolerateUnknown })
|
|
1624
|
+
}
|
|
1625
|
+
|
|
1626
|
+
if (!this.imports.has(key)) this.imports.set(key, new Map())
|
|
1627
|
+
const imports = this.imports.get(key)
|
|
1628
|
+
if (!imports.has(parent)) imports.set(parent, new Map())
|
|
1629
|
+
const specifiers = imports.get(parent)
|
|
1630
|
+
noupsert(specifiers, specifier, file)
|
|
1631
|
+
if (format) noupsert(this.formats, file, format)
|
|
1632
|
+
}
|
|
1633
|
+
|
|
1634
|
+
getImport(parentURL, specifier, { conditions = '*', importAttributes } = {}) {
|
|
1635
|
+
if (conditions !== '*') assert.ok(Array.isArray(conditions))
|
|
1636
|
+
assert.ok(parentURL, 'getImport requires a parent') // matches addImport; #canonicalSpecifier needs it
|
|
1637
|
+
const parent = this.#canonicalFile(parentURL)
|
|
1638
|
+
specifier = this.#canonicalSpecifier(parentURL, specifier)
|
|
1639
|
+
const key = this.#conditionsKey(conditions, importAttributes)
|
|
1640
|
+
// Statically-built bundles (e.g. `stasis bundle src/entry.js`) resolve edges
|
|
1641
|
+
// offline and store them under the wildcard '*' key, since they can't
|
|
1642
|
+
// predict the exact condition set Node will pass at load time. The runtime
|
|
1643
|
+
// loader always records the precise conditions Node reported, so the
|
|
1644
|
+
// specific lookup wins when a runtime bundle is in play and only static
|
|
1645
|
+
// bundles take the wildcard fallback. Mismatches between the resolved file
|
|
1646
|
+
// for a given (parent, spec) under the two condition sets remain caller
|
|
1647
|
+
// territory -- the static bundle is authoritative for whichever conditions
|
|
1648
|
+
// the static resolver used.
|
|
1649
|
+
let file = this.imports.get(key)?.get(parent)?.get(specifier)
|
|
1650
|
+
if (file === undefined && key !== '*') {
|
|
1651
|
+
file = this.imports.get('*')?.get(parent)?.get(specifier)
|
|
1652
|
+
}
|
|
1653
|
+
if (file === undefined) {
|
|
1654
|
+
// The (key, parent, spec) and '*' lookups missed, but the edge may be recorded
|
|
1655
|
+
// under a DIFFERENT conditions bucket -- e.g. the esbuild plugin asks with
|
|
1656
|
+
// conditions='*' while a Node-loader-captured bundle keyed the edge under
|
|
1657
|
+
// 'require, node, ...'. resolveBundled scans every bucket for the recorded edge.
|
|
1658
|
+
if (this.config.loadBundle) {
|
|
1659
|
+
const abs = this.resolveBundled(parentURL, specifier)
|
|
1660
|
+
if (abs !== undefined) {
|
|
1661
|
+
const f = relative(this.root, abs)
|
|
1662
|
+
return { url: pathToFileURL(abs).toString(), format: this.formats.get(f) }
|
|
1663
|
+
}
|
|
1664
|
+
}
|
|
1665
|
+
// Throw with Node's ERR_MODULE_NOT_FOUND shape rather than asserting:
|
|
1666
|
+
// plain Node's resolver throws this when a bare or relative specifier
|
|
1667
|
+
// can't be found, and ESM dynamic-import callers commonly do
|
|
1668
|
+
// `try { await import(x) } catch (e) { if (e.code !== 'ERR_MODULE_NOT_FOUND') throw e }`.
|
|
1669
|
+
// A bare assertion produced an ERR_ASSERTION code that re-threw out of
|
|
1670
|
+
// those guards.
|
|
1671
|
+
const err = new Error(`Cannot find module '${specifier}' imported from ${parent}`)
|
|
1672
|
+
err.code = 'ERR_MODULE_NOT_FOUND'
|
|
1673
|
+
throw err
|
|
1674
|
+
}
|
|
1675
|
+
// A `stasis bundle --metro` artifact records a { platform: file } Map for an
|
|
1676
|
+
// edge that resolves differently per platform. Plain `stasis run --bundle=load`
|
|
1677
|
+
// has no platform context to pick one, so it can't serve such an edge -- fail
|
|
1678
|
+
// closed with a clear error rather than feeding a Map where a path is expected.
|
|
1679
|
+
if (typeof file !== 'string') {
|
|
1680
|
+
const err = new Error(`Resolution of '${specifier}' from ${parent} is platform-specific (a --metro multi-platform bundle); it can't be loaded by plain node, build a single-platform bundle to load`)
|
|
1681
|
+
err.code = 'ERR_STASIS_PLATFORM_SPECIFIC'
|
|
1682
|
+
throw err
|
|
1683
|
+
}
|
|
1684
|
+
const url = pathToFileURL(resolve(this.root, file)).toString()
|
|
1685
|
+
const format = this.formats.get(file) // might be undefined e.g. for some bundlers
|
|
1686
|
+
return { url, format }
|
|
1687
|
+
}
|
|
1688
|
+
|
|
1689
|
+
// Resolve a CommonJS require() target to a bundled file, returning the absolute
|
|
1690
|
+
// path the loader should use (load() then serves its bytes from the bundle), or
|
|
1691
|
+
// undefined to defer to Node's native resolution.
|
|
1692
|
+
//
|
|
1693
|
+
// Node's CommonJS loader resolves require() through Module._resolveFilename, which
|
|
1694
|
+
// registerHooks does NOT intercept. When the ESM->CJS translator runs a CJS module we
|
|
1695
|
+
// served from the bundle (`import chalk from 'chalk'`, chalk being CJS), that module's
|
|
1696
|
+
// nested require()s take this native path and Node resolves them against disk -- so a
|
|
1697
|
+
// bundle is not self-contained for a CJS dependency graph once node_modules is
|
|
1698
|
+
// pruned/absent. The CJS-loader shim in hooks.js consults this to serve them from the
|
|
1699
|
+
// bundle instead.
|
|
1700
|
+
//
|
|
1701
|
+
// Returns the recorded edge for this (parent, specifier) under ANY conditions bucket --
|
|
1702
|
+
// a native require gives no conditions to key on, and divergent targets across buckets
|
|
1703
|
+
// are ambiguous, so we defer. EVERY require() edge is recorded at capture, including the
|
|
1704
|
+
// sibling requires Node's module cache used to hide from the resolve hook (the
|
|
1705
|
+
// Module._load shim in hooks.js observes them) -- so a miss here means the bundle simply
|
|
1706
|
+
// doesn't carry the target (an external), and we defer to Node rather than guess.
|
|
1707
|
+
resolveBundled(parentURL, specifier) {
|
|
1708
|
+
let parent
|
|
1709
|
+
try { parent = this.#canonicalFile(parentURL) } catch { return undefined }
|
|
1710
|
+
const spec = this.#canonicalSpecifier(parentURL, specifier)
|
|
1711
|
+
const matches = new Set()
|
|
1712
|
+
for (const [, byParent] of this.imports) {
|
|
1713
|
+
const file = byParent.get(parent)?.get(spec)
|
|
1714
|
+
if (file !== undefined) matches.add(file)
|
|
1715
|
+
}
|
|
1716
|
+
return matches.size === 1 ? resolve(this.root, [...matches][0]) : undefined
|
|
1717
|
+
}
|
|
1718
|
+
|
|
1719
|
+
// Union of the lockfile-attested resolutions and the live map (observed at
|
|
1720
|
+
// runtime and/or carried over from a loaded bundle), so a partial lock=add
|
|
1721
|
+
// run extends the recorded resolutions without dropping edges it didn't
|
|
1722
|
+
// reach. Conflicting targets for the same edge are fatal (add semantics,
|
|
1723
|
+
// same as hashes).
|
|
1724
|
+
#mergedImports() {
|
|
1725
|
+
const merged = new Map()
|
|
1726
|
+
const mergeIn = (imports) => {
|
|
1727
|
+
for (const [conditions, byParent] of imports) {
|
|
1728
|
+
if (!merged.has(conditions)) merged.set(conditions, new Map())
|
|
1729
|
+
const mergedParents = merged.get(conditions)
|
|
1730
|
+
for (const [parent, specifiers] of byParent) {
|
|
1731
|
+
if (!mergedParents.has(parent)) mergedParents.set(parent, new Map())
|
|
1732
|
+
const mergedSpecifiers = mergedParents.get(parent)
|
|
1733
|
+
for (const [specifier, file] of specifiers) {
|
|
1734
|
+
noupsert(mergedSpecifiers, specifier, file)
|
|
1735
|
+
}
|
|
1736
|
+
}
|
|
1737
|
+
}
|
|
1738
|
+
}
|
|
1739
|
+
if (this.#lockImports) mergeIn(this.#lockImports)
|
|
1740
|
+
mergeIn(this.imports)
|
|
1741
|
+
// Union sidecars' imports too: a bundler-plugin's sidecar records the
|
|
1742
|
+
// webpack-graph edges into its own this.imports, and the lockfile must
|
|
1743
|
+
// attest those edges so a frozen run can verify them.
|
|
1744
|
+
for (const sidecar of this.#sidecars) mergeIn(sidecar.imports)
|
|
1745
|
+
return merged
|
|
1746
|
+
}
|
|
1747
|
+
|
|
1748
|
+
// Union of lockfile-attested and observed/bundle-served formats, same
|
|
1749
|
+
// append-only stance as #mergedImports: conflicting formats for one file are
|
|
1750
|
+
// fatal (noupsert). Sidecars' formats are unioned in for the same reason.
|
|
1751
|
+
#mergedFormats() {
|
|
1752
|
+
const merged = new Map()
|
|
1753
|
+
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)
|
|
1755
|
+
for (const sidecar of this.#sidecars) {
|
|
1756
|
+
for (const [file, format] of sidecar.formats) noupsert(merged, file, format)
|
|
1757
|
+
}
|
|
1758
|
+
return merged
|
|
1759
|
+
}
|
|
1760
|
+
|
|
1761
|
+
get lockData() {
|
|
1762
|
+
return new Lockfile({
|
|
1763
|
+
config: this.config.values,
|
|
1764
|
+
entries: this.entries,
|
|
1765
|
+
modules: this.modules,
|
|
1766
|
+
imports: this.#mergedImports(),
|
|
1767
|
+
formats: this.#mergedFormats(),
|
|
1768
|
+
}).serialize()
|
|
1769
|
+
}
|
|
1770
|
+
|
|
1771
|
+
// Pair each module's recorded file list with the corresponding content from
|
|
1772
|
+
// perFile (state.sources for code, state.resources for resources), dropping
|
|
1773
|
+
// modules with no content. Bundle.serialize* then groups them into sources/
|
|
1774
|
+
// modules buckets and writes the lockfile-shaped output.
|
|
1775
|
+
#bundleModules(perFile) {
|
|
1776
|
+
const modules = new Map()
|
|
1777
|
+
for (const [dir, info] of this.modules) {
|
|
1778
|
+
const files = {}
|
|
1779
|
+
for (const rel of Object.keys(info.files)) {
|
|
1780
|
+
const file = moduleFileKey(dir, rel)
|
|
1781
|
+
const content = perFile.get(file)
|
|
1782
|
+
if (content !== undefined) files[rel] = content
|
|
1783
|
+
}
|
|
1784
|
+
if (Object.keys(files).length > 0) {
|
|
1785
|
+
modules.set(dir, info.ecosystem === undefined
|
|
1786
|
+
? { name: info.name, version: info.version, files }
|
|
1787
|
+
: { name: info.name, version: info.version, ecosystem: info.ecosystem, files })
|
|
1788
|
+
}
|
|
1789
|
+
}
|
|
1790
|
+
return modules
|
|
1791
|
+
}
|
|
1792
|
+
|
|
1793
|
+
// A bundler plugin instance has attached to this State (called from resolvePluginState at the
|
|
1794
|
+
// plugin's construction). Files this run merely fs-READS *after* this point that a plugin also
|
|
1795
|
+
// bundles are the plugin's modules, not run's -- see #bundleReason. Idempotent. Public so it
|
|
1796
|
+
// works across stasis-core copies (the plugin may be a foreign-copy instance), like
|
|
1797
|
+
// registerSidecar / sidecarInheritance.
|
|
1798
|
+
markPluginAttached() {
|
|
1799
|
+
this.#pluginAttached = true
|
|
1800
|
+
}
|
|
1801
|
+
|
|
1802
|
+
// Record which consumer (`reason`) observed `file`, for the bundle's informational `reason` map.
|
|
1803
|
+
#recordReason(reason, file) {
|
|
1804
|
+
let set = this.#reasonFiles.get(reason)
|
|
1805
|
+
if (set === undefined) this.#reasonFiles.set(reason, set = new Set())
|
|
1806
|
+
set.add(file)
|
|
1807
|
+
}
|
|
1808
|
+
|
|
1809
|
+
// Build the bundle's informational `reason` map, restricted to `bundledFiles` (this bundle's own
|
|
1810
|
+
// file set): { consumer: [files] } for each consumer that recorded at least one file in it.
|
|
1811
|
+
// Returned ONLY when more than one consumer contributed -- a single-consumer bundle (plain `run`,
|
|
1812
|
+
// or a standalone plugin) omits it. Never attested; purely for humans / tooling.
|
|
1813
|
+
#bundleReason(bundledFiles) {
|
|
1814
|
+
const inBundle = bundledFiles instanceof Set ? bundledFiles : new Set(bundledFiles)
|
|
1815
|
+
// Files some PLUGIN bundles (any consumer other than 'run'). A file run merely fs-READ (never
|
|
1816
|
+
// imported) after a plugin attached, that a plugin also bundles, is the plugin's module -- e.g.
|
|
1817
|
+
// webpack+babel reading app source through --fs to transform it -- so 'run' must not claim it.
|
|
1818
|
+
const pluginFiles = new Set()
|
|
1819
|
+
for (const [who, recorded] of this.#reasonFiles) {
|
|
1820
|
+
if (who === 'run') continue
|
|
1821
|
+
for (const file of recorded) pluginFiles.add(file)
|
|
1822
|
+
}
|
|
1823
|
+
const runOverclaims = (file) =>
|
|
1824
|
+
this.#fsReadPostPlugin.has(file) && !this.#runImported.has(file) && pluginFiles.has(file)
|
|
1825
|
+
|
|
1826
|
+
const reason = {}
|
|
1827
|
+
let consumers = 0
|
|
1828
|
+
// Sort consumer keys AND each file list, like every other map in the bundle (sortPaths, via
|
|
1829
|
+
// fileMapToObject etc.): the emitted JSON must be byte-reproducible across runs regardless of
|
|
1830
|
+
// loader-vs-plugin record order, else #emitBundle's compare-and-skip would see spurious diffs.
|
|
1831
|
+
for (const who of [...this.#reasonFiles.keys()].toSorted()) {
|
|
1832
|
+
const files = []
|
|
1833
|
+
for (const file of this.#reasonFiles.get(who)) {
|
|
1834
|
+
if (!inBundle.has(file)) continue
|
|
1835
|
+
if (who === 'run' && runOverclaims(file)) continue
|
|
1836
|
+
files.push(file)
|
|
1837
|
+
}
|
|
1838
|
+
if (files.length > 0) { reason[who] = files.toSorted(sortPaths); consumers += 1 }
|
|
1839
|
+
}
|
|
1840
|
+
return consumers > 1 ? reason : undefined
|
|
1841
|
+
}
|
|
1842
|
+
|
|
1843
|
+
get sourceBundle() {
|
|
1844
|
+
// One bundle holds both code and resources; merge the two content maps (their key
|
|
1845
|
+
// sets are disjoint -- a file is either code or a resource) and let `formats` tag
|
|
1846
|
+
// which is which. Resource payloads are already encoded per their format. The
|
|
1847
|
+
// disjointness invariant is enforced upstream in addFile via noupsert on
|
|
1848
|
+
// this.formats (a file's format is either a resource one or not, and cannot
|
|
1849
|
+
// change), so an overlap here would be a real bug -- assert it explicitly at
|
|
1850
|
+
// the merge site so the failure is local, not a silently-clobbered value.
|
|
1851
|
+
const contents = new Map(this.sources)
|
|
1852
|
+
for (const [file, content] of this.resources) {
|
|
1853
|
+
assert.ok(!contents.has(file), `state invariant: file ${file} in both sources and resources`)
|
|
1854
|
+
contents.set(file, content)
|
|
1855
|
+
}
|
|
1856
|
+
return new Bundle({
|
|
1857
|
+
config: this.config.values,
|
|
1858
|
+
entries: this.entries,
|
|
1859
|
+
modules: this.#bundleModules(contents),
|
|
1860
|
+
formats: this.formats,
|
|
1861
|
+
imports: this.imports,
|
|
1862
|
+
reason: this.#bundleReason(contents.keys()),
|
|
1863
|
+
})
|
|
1864
|
+
}
|
|
1865
|
+
|
|
1866
|
+
get sourceData() {
|
|
1867
|
+
return this.sourceBundle.serialize()
|
|
1868
|
+
}
|
|
1869
|
+
|
|
1870
|
+
// Split-bundle counterparts to `sourceBundle` / `sourceData`. Used by `write()`
|
|
1871
|
+
// when `config.resourcesBundleFile` is set so the on-disk layout matches a
|
|
1872
|
+
// bundle=load reader. Each is a standalone v1 Bundle (independently parseable);
|
|
1873
|
+
// metadata is partitioned, not duplicated -- the code half owns entries/imports
|
|
1874
|
+
// and code-format declarations, the resources half owns resource-format
|
|
1875
|
+
// declarations and the resource bytes. Both halves declare their per-dir
|
|
1876
|
+
// module identity (name/version) so each file is verifiable on its own.
|
|
1877
|
+
get codeBundle() {
|
|
1878
|
+
// Resource files don't appear in `this.sources` (addFile routes by format), so
|
|
1879
|
+
// restricting #bundleModules to `this.sources` automatically yields the code-only
|
|
1880
|
+
// view. Formats and modules are filtered to drop resource-only dirs/files.
|
|
1881
|
+
const codeFormats = new Map()
|
|
1882
|
+
for (const [file, format] of this.formats) {
|
|
1883
|
+
if (!Bundle.isResourceFormat(format)) codeFormats.set(file, format)
|
|
1884
|
+
}
|
|
1885
|
+
return new Bundle({
|
|
1886
|
+
config: this.config.values,
|
|
1887
|
+
entries: this.entries,
|
|
1888
|
+
modules: this.#bundleModules(this.sources),
|
|
1889
|
+
formats: codeFormats,
|
|
1890
|
+
imports: this.imports,
|
|
1891
|
+
reason: this.#bundleReason(this.sources.keys()),
|
|
1892
|
+
})
|
|
1893
|
+
}
|
|
1894
|
+
|
|
1895
|
+
get resourcesBundle() {
|
|
1896
|
+
const resourceFormats = new Map()
|
|
1897
|
+
for (const [file, format] of this.formats) {
|
|
1898
|
+
if (Bundle.isResourceFormat(format)) resourceFormats.set(file, format)
|
|
1899
|
+
}
|
|
1900
|
+
return new Bundle({
|
|
1901
|
+
config: this.config.values,
|
|
1902
|
+
// Resources bundle carries no entries / imports -- those belong to the code half.
|
|
1903
|
+
// Bundle.parse accepts an empty entries set when no code is present (the hasCode
|
|
1904
|
+
// check sees only resource-format files and waives the requirement).
|
|
1905
|
+
entries: new Set(),
|
|
1906
|
+
modules: this.#bundleModules(this.resources),
|
|
1907
|
+
formats: resourceFormats,
|
|
1908
|
+
imports: new Map(),
|
|
1909
|
+
reason: this.#bundleReason(this.resources.keys()),
|
|
1910
|
+
})
|
|
1911
|
+
}
|
|
1912
|
+
|
|
1913
|
+
// Record a capture-time native resolution (from the Module._resolveFilename
|
|
1914
|
+
// shim). Stored verbatim; #backfillObservedResolutions decides at write() which
|
|
1915
|
+
// to add. Last-write-wins per (parent, specifier) so duplicates collapse.
|
|
1916
|
+
observeResolution(parentURL, specifier, resolvedURL) {
|
|
1917
|
+
let byParent = this.#observedResolutions.get(parentURL)
|
|
1918
|
+
if (byParent === undefined) this.#observedResolutions.set(parentURL, (byParent = new Map()))
|
|
1919
|
+
byParent.set(specifier, resolvedURL)
|
|
1920
|
+
}
|
|
1921
|
+
|
|
1922
|
+
// Backfill resolution edges the live resolve hook never observed -- require.resolve()
|
|
1923
|
+
// (and CJS require()s that resolve natively) on Node versions where they bypass
|
|
1924
|
+
// the hook. Records BOTH kinds the hook missed:
|
|
1925
|
+
// - under-recorded require()s whose target the bundle carries (Node's module
|
|
1926
|
+
// cache hid the require() from the resolve hook -- another module loaded the
|
|
1927
|
+
// target first), and
|
|
1928
|
+
// - resolve-only edges whose target it does NOT carry: require.resolve() of a
|
|
1929
|
+
// module never loaded in-process (an optional-dependency probe, a forked-
|
|
1930
|
+
// worker child like worker-farm's, a .node addon). The resolution is real and
|
|
1931
|
+
// must be attested so the same require.resolve() returns the same path at
|
|
1932
|
+
// 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.
|
|
1934
|
+
// Guards:
|
|
1935
|
+
// - skip out-of-scope targets (mirroring #collectMissingImportedFiles) so a
|
|
1936
|
+
// node_modules-scope artifact doesn't attest workspace resolutions it isn't
|
|
1937
|
+
// responsible for; an in-bundle target is always in scope, so it's exempt.
|
|
1938
|
+
// (Targets escaping the root throw in #canonicalFile -> caught below.)
|
|
1939
|
+
// - only edges the hook didn't already record (dedup across all condition
|
|
1940
|
+
// buckets), so this never double-records a normal require().
|
|
1941
|
+
// Keyed under the observed require-condition set (#requireConditions) -- require()/
|
|
1942
|
+
// require.resolve() resolve under those conditions, not condition-free -- so a
|
|
1943
|
+
// native-resolve Node (where these edges land here) keys them the same way the
|
|
1944
|
+
// resolve hook keys them directly on newer Node. Any capture that does at least one
|
|
1945
|
+
// require() thus yields the same lockfile on every version; '*' only when the set was
|
|
1946
|
+
// never observed (a capture with no require() at all), which getImport/resolveBundled
|
|
1947
|
+
// still match via their wildcard fallback.
|
|
1948
|
+
#backfillObservedResolutions() {
|
|
1949
|
+
if (this.#observedResolutions.size === 0) return
|
|
1950
|
+
for (const [parentURL, specs] of this.#observedResolutions) {
|
|
1951
|
+
let parent
|
|
1952
|
+
try { parent = this.#canonicalFile(parentURL) } catch { continue }
|
|
1953
|
+
for (const [specifier, resolvedURL] of specs) {
|
|
1954
|
+
let file
|
|
1955
|
+
try { file = this.#canonicalFile(resolvedURL) } catch { continue }
|
|
1956
|
+
const bundled = this.sources.has(file) || this.resources.has(file)
|
|
1957
|
+
if (!bundled && !this.config.full && !this.inNodeModules(resolvedURL)) continue
|
|
1958
|
+
const spec = this.#canonicalSpecifier(parentURL, specifier)
|
|
1959
|
+
let recorded = false
|
|
1960
|
+
for (const [, byParent] of this.imports) {
|
|
1961
|
+
if (byParent.get(parent)?.get(spec) !== undefined) { recorded = true; break }
|
|
1962
|
+
}
|
|
1963
|
+
if (!recorded) this.addImport(parentURL, specifier, resolvedURL, { conditions: this.#requireConditions ?? '*' })
|
|
1964
|
+
}
|
|
1965
|
+
}
|
|
1966
|
+
}
|
|
1967
|
+
|
|
1968
|
+
write() {
|
|
1969
|
+
// Backfill observed (native Module._resolveFilename) resolutions BEFORE the
|
|
1970
|
+
// stasis-core BFS. On Node's native-resolve versions a resolve-only edge to a
|
|
1971
|
+
// stasis-core src/*.js submodule (e.g. require.resolve('@exodus/stasis-core/
|
|
1972
|
+
// prune') of a module never loaded) is added only here; running the BFS first
|
|
1973
|
+
// would compute its missing-set without that edge, never seed the file, and
|
|
1974
|
+
// ship a dangling edge with no bytes -- which a later lock=frozen replay then
|
|
1975
|
+
// rejects. Recording it first lets the BFS capture the bytes, matching what the
|
|
1976
|
+
// resolve-hook path already records in-line on newer Node. Order is otherwise
|
|
1977
|
+
// independent: the BFS doesn't read #observedResolutions, and observe-backfill's
|
|
1978
|
+
// `bundled` check sees files loaded during capture (already in this.sources)
|
|
1979
|
+
// regardless of when the BFS runs.
|
|
1980
|
+
this.#backfillObservedResolutions()
|
|
1981
|
+
this.#backfillBeforeWrite()
|
|
1982
|
+
// writeFileSync(join(this.root, FILE_CONFIG), this.config.json)
|
|
1983
|
+
// Sidecars never write the lockfile -- the parent owns it. They only emit their bundle.
|
|
1984
|
+
// A "sidecar" here is one sharing the parent's lockfile data structures; an independent
|
|
1985
|
+
// State with its own lockFile path (constructed via the no-parent code path) writes its
|
|
1986
|
+
// own lockfile to `config.lockFile` instead of the rootDir default.
|
|
1987
|
+
//
|
|
1988
|
+
// Per-artifact compare-and-skip: each output's serialized text is compared against the
|
|
1989
|
+
// cached previous text and the brotli + writeFileSync are both skipped when they match.
|
|
1990
|
+
// Critical for webpack/esbuild watch-mode rebuilds, where compiler.hooks.done fires on
|
|
1991
|
+
// every rebuild but the captured graph usually doesn't change. Without this, every
|
|
1992
|
+
// rebuild brotli-compresses (quality 11) and rewrites every output.
|
|
1993
|
+
|
|
1994
|
+
if (this.config.writeLockfile && !this.#parent) {
|
|
1995
|
+
const lockText = this.lockData
|
|
1996
|
+
if (lockText !== this.#lastLockData) {
|
|
1997
|
+
const lockPath = this.config.lockFile || join(this.root, FILE_LOCK)
|
|
1998
|
+
mkdirSync(dirname(lockPath), { recursive: true })
|
|
1999
|
+
writeFileSync(lockPath, lockText)
|
|
2000
|
+
this.#lastLockData = lockText
|
|
2001
|
+
}
|
|
2002
|
+
}
|
|
2003
|
+
if (this.config.writeBundle) {
|
|
2004
|
+
const sourcesPath = this.config.bundleFile || join(this.root, FILE_CODE)
|
|
2005
|
+
if (this.config.resourcesBundleFile) {
|
|
2006
|
+
// Split-bundle layout: code-only to bundleFile, resources-only to resourcesBundleFile.
|
|
2007
|
+
// Each is a standalone v1 Bundle (cross-check on load enforces shape). hasContent
|
|
2008
|
+
// gates per half so an empty half (no code / no resources) is dropped under replace
|
|
2009
|
+
// rather than written as an empty bundle -- see #emitBundle. sources/resources size
|
|
2010
|
+
// is the exact emptiness test: a code bundle's entries/imports are non-empty only
|
|
2011
|
+
// when sources are (every entry/edge parent is itself an addFile'd source).
|
|
2012
|
+
this.#lastCodeBundle = this.#emitBundle(
|
|
2013
|
+
sourcesPath, this.sources.size > 0, this.#lastCodeBundle, () => this.codeBundle.serialize())
|
|
2014
|
+
this.#lastResourcesBundle = this.#emitBundle(
|
|
2015
|
+
this.config.resourcesBundleFile, this.resources.size > 0, this.#lastResourcesBundle,
|
|
2016
|
+
() => this.resourcesBundle.serialize())
|
|
2017
|
+
} else {
|
|
2018
|
+
this.#lastUnifiedBundle = this.#emitBundle(
|
|
2019
|
+
sourcesPath, this.sources.size > 0 || this.resources.size > 0, this.#lastUnifiedBundle,
|
|
2020
|
+
() => this.sourceData)
|
|
2021
|
+
}
|
|
2022
|
+
}
|
|
2023
|
+
}
|
|
2024
|
+
|
|
2025
|
+
// Produce the lockfile-shaped snapshot of everything THIS process captured, for a child
|
|
2026
|
+
// process to hand back to the root (which never loaded what only the child loaded -- e.g.
|
|
2027
|
+
// a Metro transform worker loading babel.config.js + its babel preset/plugins). Runs the
|
|
2028
|
+
// same backfills write() runs so observed native (Module._resolveFilename) resolutions and
|
|
2029
|
+
// stasis-core internal edges are materialized first. Content is intentionally omitted: the
|
|
2030
|
+
// snapshot carries project-relative paths + the import graph + formats + entries, and the
|
|
2031
|
+
// root re-reads each file's bytes from disk when it replays via mergeShard().
|
|
2032
|
+
shardSnapshot() {
|
|
2033
|
+
this.#backfillObservedResolutions()
|
|
2034
|
+
this.#backfillBeforeWrite()
|
|
2035
|
+
// Forward ONLY what THIS process observed this run -- not the baseline it seeded at construction.
|
|
2036
|
+
// On a lock=add re-run the root seeds the same lockfile baseline (and a BUNDLE run seeds the
|
|
2037
|
+
// whole bundle graph), so re-shipping it would bloat every worker's shard (toward
|
|
2038
|
+
// MAX_SHARD_BYTES, past which mergeChildShards silently drops it) and make the root re-merge it
|
|
2039
|
+
// once per worker. #observed holds the files addFile/addFsDir recorded this run; modules, formats
|
|
2040
|
+
// AND imports are all filtered to it below. (Lockfile-seeded edges/formats live in
|
|
2041
|
+
// #lockImports/#lockFormats, but a bundle load seeds this.imports/this.formats DIRECTLY -- so we
|
|
2042
|
+
// filter explicitly rather than rely on which map holds the baseline.) Entries are dropped:
|
|
2043
|
+
// mergeShard never marks a merged file as an entry, and this.entries is itself seeded.
|
|
2044
|
+
const modules = new Map()
|
|
2045
|
+
for (const [dir, info] of this.modules) {
|
|
2046
|
+
const files = {}
|
|
2047
|
+
for (const rel of Object.keys(info.files)) {
|
|
2048
|
+
if (this.#observed.has(moduleFileKey(dir, rel))) files[rel] = info.files[rel]
|
|
2049
|
+
}
|
|
2050
|
+
if (Object.keys(files).length === 0) continue
|
|
2051
|
+
modules.set(dir, info.ecosystem === undefined
|
|
2052
|
+
? { name: info.name, version: info.version, files }
|
|
2053
|
+
: { name: info.name, version: info.version, ecosystem: info.ecosystem, files })
|
|
2054
|
+
}
|
|
2055
|
+
// formats: only observed files. imports: only edges whose PARENT was observed -- a child adds an
|
|
2056
|
+
// edge solely from a file it loaded (addImport's parent is addFile'd -> in #observed), so its
|
|
2057
|
+
// session edges are kept while bundle-seeded edges (parent never loaded here) are dropped; the
|
|
2058
|
+
// root already attests those from its own seed, so dropping them loses nothing.
|
|
2059
|
+
const formats = new Map()
|
|
2060
|
+
for (const file of this.#observed) {
|
|
2061
|
+
const fmt = this.formats.get(file)
|
|
2062
|
+
if (fmt !== undefined) formats.set(file, fmt)
|
|
2063
|
+
}
|
|
2064
|
+
const imports = new Map()
|
|
2065
|
+
for (const [conditions, byParent] of this.imports) {
|
|
2066
|
+
let kept
|
|
2067
|
+
for (const [parent, specs] of byParent) {
|
|
2068
|
+
if (!this.#observed.has(parent)) continue
|
|
2069
|
+
if (kept === undefined) { kept = new Map(); imports.set(conditions, kept) }
|
|
2070
|
+
kept.set(parent, specs)
|
|
2071
|
+
}
|
|
2072
|
+
}
|
|
2073
|
+
return new Lockfile({
|
|
2074
|
+
config: this.config.values,
|
|
2075
|
+
entries: new Set(),
|
|
2076
|
+
modules,
|
|
2077
|
+
imports,
|
|
2078
|
+
formats,
|
|
2079
|
+
}).serialize()
|
|
2080
|
+
}
|
|
2081
|
+
|
|
2082
|
+
// Merge a child process's shardSnapshot() (a serialized lockfile) into this State, as if
|
|
2083
|
+
// this process had loaded/read those files itself: replay each file (addFile for code +
|
|
2084
|
+
// `--fs` resources, addFsDir for `--fs` directory captures -- re-reading bytes/listings from
|
|
2085
|
+
// disk to hash + classify) and addImport each recorded edge. This is how the root attests files and
|
|
2086
|
+
// edges that ONLY a forked child observed -- the child runs the loader and captures into
|
|
2087
|
+
// its own State but is blocked from writing, so without this its observations are lost.
|
|
2088
|
+
// Project-relative paths are shared across the process tree (same root); URLs are
|
|
2089
|
+
// reconstructed via resolve(this.root, file). Best-effort per record: a path gone from disk
|
|
2090
|
+
// (a transient temp module) or rejected by addFile/addImport (out of this run's scope) is
|
|
2091
|
+
// skipped rather than aborting the whole merge -- the root's own capture stays intact.
|
|
2092
|
+
mergeShard(lockText) {
|
|
2093
|
+
const lf = Lockfile.parse(lockText)
|
|
2094
|
+
// A shard must describe the SAME scope as this root (children inherit scope via env, so they
|
|
2095
|
+
// always agree). Defense-in-depth: a cross-scope shard is already signature-rejected upstream,
|
|
2096
|
+
// but a mismatch here would mean a malformed/foreign shard -- refuse it rather than merge.
|
|
2097
|
+
assert.equal(lf.config.scope, this.config.scope, `shard scope "${lf.config.scope}" != root scope "${this.config.scope}"`)
|
|
2098
|
+
// Files first (so addFile records bytes/format/module identity), then edges. Merged files
|
|
2099
|
+
// are NEVER marked entries: a forked child's "entry" is its fork-target main (e.g. a Metro
|
|
2100
|
+
// worker's bootstrap), not a declared entry of the ROOT build -- recording it as one would
|
|
2101
|
+
// corrupt the root's entries list. The child's lf.entries is therefore ignored here.
|
|
2102
|
+
for (const [dir, info] of lf.modules) {
|
|
2103
|
+
for (const rel of Object.keys(info.files)) {
|
|
2104
|
+
// moduleFileKey is the exact inverse of how the child bucketed the path -- in particular
|
|
2105
|
+
// it yields `dir` (no trailing slash) for a directory captured AT a bucket root (rel==='').
|
|
2106
|
+
const file = moduleFileKey(dir, rel)
|
|
2107
|
+
// Skip a file the root already attests -- its seeded lockfile baseline or its own capture
|
|
2108
|
+
// this run. A child only needs to contribute what the root didn't observe; re-reading an
|
|
2109
|
+
// already-recorded file from disk (per worker shard) is the dominant merge cost, and since
|
|
2110
|
+
// this loop adds to this.hashes, identical toolchain files from later workers skip too.
|
|
2111
|
+
// EXCEPTION: still carry a concrete code format the root LACKS. If the root fs-READ this
|
|
2112
|
+
// `.js`/`.ts` (addFsFile records the hash but NO format) while the child IMPORTED it as
|
|
2113
|
+
// `module`, dropping the format here would leave the lockfile format-less and make a later
|
|
2114
|
+
// frozen run -- where the file loads as a module -- reject the now-unattested format. Fall
|
|
2115
|
+
// through so addFile records (and validates) the format; the byte re-read is the only cost.
|
|
2116
|
+
if (this.hashes.has(file)) {
|
|
2117
|
+
const shardFormat = lf.formats?.get(file)
|
|
2118
|
+
if (shardFormat === undefined || (this.formats.get(file) ?? this.#lockFormats?.get(file)) !== undefined) continue
|
|
2119
|
+
}
|
|
2120
|
+
const absolute = resolve(this.root, file)
|
|
2121
|
+
const url = pathToFileURL(absolute).toString()
|
|
2122
|
+
const format = lf.formats?.get(file)
|
|
2123
|
+
try {
|
|
2124
|
+
if (format === 'directory') {
|
|
2125
|
+
// A child's `fs.readdirSync` capture (`--fs`): replay as a directory listing (addFile
|
|
2126
|
+
// rejects a directory). Re-read the listing from disk so the root's hash is
|
|
2127
|
+
// authoritative -- the same disk-is-truth stance as the byte re-reads below. Range-check
|
|
2128
|
+
// the path FIRST: addFsDir would reject a traversal, but only AFTER readdirSync already
|
|
2129
|
+
// ran on the forged out-of-root path, so a child-forged `..` key can't make us list it.
|
|
2130
|
+
const relFromRoot = relative(this.root, absolute)
|
|
2131
|
+
if (relFromRoot.startsWith('..') || isAbsolute(relFromRoot)) continue
|
|
2132
|
+
this.addFsDir(url, readdirSync(absolute))
|
|
2133
|
+
} else if (format === 'resource' || format === 'resource:base64') {
|
|
2134
|
+
// A child's `fs.readFileSync` capture of an asset: addFile needs resource:true for a
|
|
2135
|
+
// resource format. The exact 'resource' vs 'resource:base64' tag is content-derived, so
|
|
2136
|
+
// addFile re-derives it from the re-read bytes -- we don't pass it (and risk a spurious
|
|
2137
|
+
// mismatch), we just mark it a resource.
|
|
2138
|
+
this.addFile(url, { resource: true })
|
|
2139
|
+
} else if (format === undefined) {
|
|
2140
|
+
// Code file the child recorded with NO format -- it fs-READ a `.js`/`.ts` (or
|
|
2141
|
+
// `.jsx`/`.tsx`), where addFsFile defers module-vs-commonjs to the loader rather than
|
|
2142
|
+
// imposing one (Node's syntax-detection call). Replay the same way (inferFormat:false):
|
|
2143
|
+
// record the bytes but impose no format, so we don't bake in the legacy commonjs
|
|
2144
|
+
// default and collide -- at the frozen format check, or noupsert -- with the `module`
|
|
2145
|
+
// the loader records when that file is later imported. (Babel reading a worker's source
|
|
2146
|
+
// `.js` to transform it is exactly this case under `--fs --child-process`.)
|
|
2147
|
+
this.addFile(url, { inferFormat: false })
|
|
2148
|
+
} else {
|
|
2149
|
+
// Code file with a concrete loader format the child recorded (it imported the file, or
|
|
2150
|
+
// fs-read an unambiguous `.mjs`/`.cjs`/`.json`). Carry it: without it, a child-only ESM
|
|
2151
|
+
// `.js`/`.ts` under a no-`type` package would re-default to commonjs, and the subsequent
|
|
2152
|
+
// frozen run -- where the child re-loads it as module -- would reject the mismatch.
|
|
2153
|
+
// addFile still asserts the format agrees with an explicit package.json `type` when one
|
|
2154
|
+
// exists, so this can't smuggle a wrong format.
|
|
2155
|
+
this.addFile(url, { format })
|
|
2156
|
+
}
|
|
2157
|
+
} catch {
|
|
2158
|
+
// A file the child loaded but that's gone/unreadable here, or that addFile rejects
|
|
2159
|
+
// (e.g. an out-of-scope path under a different scope): skip it. The edge replay below
|
|
2160
|
+
// tolerates the resulting gap the same way.
|
|
2161
|
+
}
|
|
2162
|
+
}
|
|
2163
|
+
}
|
|
2164
|
+
if (lf.imports) {
|
|
2165
|
+
for (const [conditions, byParent] of lf.imports) {
|
|
2166
|
+
// Reverse #conditionsKey: '*' stays '*'; otherwise the key is a ', '-joined condition
|
|
2167
|
+
// list, optionally suffixed ' (with: {json})' for import attributes. Toolchain edges
|
|
2168
|
+
// (CJS require) carry no attributes; parse them when present so attributed edges merge
|
|
2169
|
+
// under the same key the child recorded.
|
|
2170
|
+
let condStr = conditions
|
|
2171
|
+
let importAttributes
|
|
2172
|
+
const withAt = conditions.indexOf(' (with: ')
|
|
2173
|
+
if (withAt !== -1) {
|
|
2174
|
+
condStr = conditions.slice(0, withAt)
|
|
2175
|
+
try { importAttributes = JSON.parse(conditions.slice(withAt + ' (with: '.length, -1)) } catch { /* leave undefined */ }
|
|
2176
|
+
}
|
|
2177
|
+
const cond = condStr === '*' ? '*' : condStr.split(', ')
|
|
2178
|
+
for (const [parent, specs] of byParent) {
|
|
2179
|
+
const parentURL = pathToFileURL(resolve(this.root, parent)).toString()
|
|
2180
|
+
for (const [specifier, file] of specs) {
|
|
2181
|
+
const url = pathToFileURL(resolve(this.root, file)).toString()
|
|
2182
|
+
try {
|
|
2183
|
+
this.addImport(parentURL, specifier, url, { conditions: cond, importAttributes })
|
|
2184
|
+
} catch {
|
|
2185
|
+
// Same best-effort stance as addFile above.
|
|
2186
|
+
}
|
|
2187
|
+
}
|
|
2188
|
+
}
|
|
2189
|
+
}
|
|
2190
|
+
}
|
|
2191
|
+
}
|
|
2192
|
+
|
|
2193
|
+
// Emit one bundle artifact, returning its new "last serialized" cache value.
|
|
2194
|
+
// - empty (hasContent === false) under bundle=replace: this run carries nothing for
|
|
2195
|
+
// this artifact, so DELETE any file at `path` rather than write an empty bundle. A
|
|
2196
|
+
// `bundle=replace` run is authoritative -- it deliberately ignores the prior on-disk
|
|
2197
|
+
// bundle (the constructor skips loading it), so a stale file the run didn't produce
|
|
2198
|
+
// must not survive as the "old one". Returning null resets the cache so a later
|
|
2199
|
+
// non-empty write() (watch-mode rebuild) re-emits the file.
|
|
2200
|
+
// - otherwise (has content, OR empty under add): serialize and write, skipping the
|
|
2201
|
+
// brotli + writeFileSync when the text is byte-identical to the last write (the
|
|
2202
|
+
// watch-mode compare-and-skip this cache exists for). add keeps emitting an empty
|
|
2203
|
+
// bundle so the file always exists -- only replace prunes a not-written artifact.
|
|
2204
|
+
#emitBundle(path, hasContent, lastText, serialize) {
|
|
2205
|
+
if (!hasContent && this.config.replaceBundle) {
|
|
2206
|
+
rmSync(path, { force: true })
|
|
2207
|
+
return null
|
|
2208
|
+
}
|
|
2209
|
+
const text = serialize()
|
|
2210
|
+
if (text !== lastText) {
|
|
2211
|
+
mkdirSync(dirname(path), { recursive: true })
|
|
2212
|
+
writeFileSync(path, brotliCompressSync(text, brotliOptions()))
|
|
2213
|
+
return text
|
|
2214
|
+
}
|
|
2215
|
+
return lastText
|
|
2216
|
+
}
|
|
2217
|
+
|
|
2218
|
+
get parent() {
|
|
2219
|
+
return this.#parent
|
|
2220
|
+
}
|
|
2221
|
+
|
|
2222
|
+
// Capture stasis-core's own files + internal edges that the live hooks missed.
|
|
2223
|
+
// When app code (or a bundler plugin) imports a stasis-core module, Node had
|
|
2224
|
+
// it cached from preload-time -- BEFORE install() registered our hooks -- so
|
|
2225
|
+
// the resolve hook records the edge but the load hook never fires, leaving
|
|
2226
|
+
// addFile / addImport blind to the file's bytes AND its outgoing edges. This
|
|
2227
|
+
// BFS, scoped strictly to the `<root>/.../@exodus/stasis-core/src/<name>.js`
|
|
2228
|
+
// shape, walks the graph starting from missing imports targets + already-
|
|
2229
|
+
// captured stasis-core files: for each, addFile (asserting the shape),
|
|
2230
|
+
// statically scans for relative-`.js` specifiers, resolves them, and
|
|
2231
|
+
// addImports each edge. The strict shape allowlist + existsSync gate filter
|
|
2232
|
+
// out comment-noise like a `require('../../pkg/x')` sitting in a JSDoc block.
|
|
2233
|
+
//
|
|
2234
|
+
// Called from write() so every State variant (preload via beforeExit/exit;
|
|
2235
|
+
// sidecar / independent plugin States via compiler.hooks.done) gets the
|
|
2236
|
+
// same coverage.
|
|
2237
|
+
#backfillBeforeWrite() {
|
|
2238
|
+
// List what the live hooks missed first. An empty list means there's
|
|
2239
|
+
// nothing to do -- either the live hooks captured everything (the common
|
|
2240
|
+
// case for non-preload runs and for plugin-driven States that don't
|
|
2241
|
+
// touch preload-cached modules), or we're a State variant that doesn't
|
|
2242
|
+
// observe imports at all.
|
|
2243
|
+
const missing = this.#collectMissingImportedFiles()
|
|
2244
|
+
if (missing.size === 0) return
|
|
2245
|
+
|
|
2246
|
+
const isStasisCoreFile = (file) => STASIS_CORE_FILE_RE.test(`/${file}`)
|
|
2247
|
+
|
|
2248
|
+
// Split the uncaptured targets. stasis-core's own preload-cached files are the
|
|
2249
|
+
// one case we both can and must reconstruct -- bytes AND transitive edges (the
|
|
2250
|
+
// BFS below). Everything else uncaptured is a resolution we attest WITHOUT
|
|
2251
|
+
// bundling: require.resolve() of a module never loaded in-process (an optional-
|
|
2252
|
+
// dependency probe, a forked-worker child like worker-farm's), or a file Node
|
|
2253
|
+
// can't serve from a bundle anyway (a .node addon). Those edges stay in
|
|
2254
|
+
// this.imports -- the user needs the resolution pinned even though the bytes are
|
|
2255
|
+
// absent -- and we do nothing further with them here. The load-time getFile
|
|
2256
|
+
// gate, not this capture-time pass, enforces the trust boundary: an actual load
|
|
2257
|
+
// of un-bundled bytes still fails closed there, while require.resolve (which
|
|
2258
|
+
// never loads) is served the attested path.
|
|
2259
|
+
const stasisCoreMissing = [...missing].filter((file) => isStasisCoreFile(file))
|
|
2260
|
+
if (stasisCoreMissing.length === 0) return
|
|
2261
|
+
|
|
2262
|
+
const preloadRel = this.#preloadRoot ? relative(this.root, this.#preloadRoot) : null
|
|
2263
|
+
const canBackfill = preloadRel !== null && !preloadRel.startsWith('..')
|
|
2264
|
+
|
|
2265
|
+
// We have stasis-core files to reconstruct but no usable preloadRoot (no loader
|
|
2266
|
+
// present, or stasis-core is a workspace sibling not under state.root): nothing
|
|
2267
|
+
// this method can do, and a stasis-core source going uncaptured IS a real gap --
|
|
2268
|
+
// the bundle would be missing part of its own runtime. Fail loud rather than
|
|
2269
|
+
// silently ship it.
|
|
2270
|
+
assert.ok(canBackfill,
|
|
2271
|
+
`state.write() has imports referencing un-captured stasis-core files but no usable preloadRoot ` +
|
|
2272
|
+
`(preloadRoot=${this.#preloadRoot ?? 'unset'}). The live load hook missed an in-scope target -- ` +
|
|
2273
|
+
`investigate rather than silently patch: ${stasisCoreMissing.slice(0, 3).join(', ')}`)
|
|
2274
|
+
|
|
2275
|
+
const PRELOAD_CONDITIONS = ['node', 'import', 'module-sync', 'node-addons']
|
|
2276
|
+
const stasisAddFile = (file) => {
|
|
2277
|
+
// Tight invariant: every backfilled file MUST match the stasis-core
|
|
2278
|
+
// source-file shape. The caller pre-filters via isStasisCoreFile, but
|
|
2279
|
+
// asserting here keeps the contract local and catches any future code
|
|
2280
|
+
// path that forgets.
|
|
2281
|
+
assert.ok(isStasisCoreFile(file),
|
|
2282
|
+
`state.write() backfill refused: '${file}' is not a stasis-core source file ` +
|
|
2283
|
+
`(expected '.../@exodus/stasis-core/src/<name>.js')`)
|
|
2284
|
+
this.addFile(pathToFileURL(resolve(this.root, file)).toString(), { reason: null }) // backfill is a write-time self-containment step, not a consumer observation -- don't attribute it
|
|
2285
|
+
}
|
|
2286
|
+
|
|
2287
|
+
// BFS through stasis-core's module graph. Seed:
|
|
2288
|
+
// (a) the missing stasis-core files -- user-code -> stasis-core edges the
|
|
2289
|
+
// live load hook missed because Node's module cache short-circuited it.
|
|
2290
|
+
// (b) every stasis-core file already in sources -- a static `stasis
|
|
2291
|
+
// bundle` pass may have pulled one in via the live hook; we still
|
|
2292
|
+
// need to walk its transitive imports.
|
|
2293
|
+
//
|
|
2294
|
+
// For each queued file: addFile if not yet captured, then scan its
|
|
2295
|
+
// source for relative-`.js` specifiers, validate the resolved target,
|
|
2296
|
+
// addImport the edge, and queue the target. The single addFile site
|
|
2297
|
+
// covers seeds AND transitive targets -- a queued target gets addFile'd
|
|
2298
|
+
// on its next pop, no separate inner addFile call needed. BFS converges
|
|
2299
|
+
// because the matching file set is finite and `processed` dedups.
|
|
2300
|
+
const queue = [...stasisCoreMissing]
|
|
2301
|
+
for (const file of this.sources.keys()) {
|
|
2302
|
+
if (isStasisCoreFile(file)) queue.push(file)
|
|
2303
|
+
}
|
|
2304
|
+
|
|
2305
|
+
const processed = new Set()
|
|
2306
|
+
while (queue.length > 0) {
|
|
2307
|
+
const file = queue.shift()
|
|
2308
|
+
if (processed.has(file)) continue
|
|
2309
|
+
processed.add(file)
|
|
2310
|
+
if (!this.sources.has(file) && !this.resources.has(file)) stasisAddFile(file)
|
|
2311
|
+
const source = this.sources.get(file)
|
|
2312
|
+
if (typeof source !== 'string') continue
|
|
2313
|
+
const baseURL = pathToFileURL(resolve(this.root, file)).toString()
|
|
2314
|
+
const recordEdge = (specifier) => {
|
|
2315
|
+
const targetURL = new URL(specifier, baseURL).toString()
|
|
2316
|
+
const targetAbsolute = fileURLToPath(targetURL)
|
|
2317
|
+
let targetFile
|
|
2318
|
+
try { targetFile = this.relative(targetAbsolute) } catch { return }
|
|
2319
|
+
if (!isStasisCoreFile(targetFile)) return
|
|
2320
|
+
if (!existsSync(targetAbsolute)) return
|
|
2321
|
+
queue.push(targetFile)
|
|
2322
|
+
this.addImport(baseURL, specifier, targetURL, { conditions: PRELOAD_CONDITIONS })
|
|
2323
|
+
}
|
|
2324
|
+
// (1) ESM `from './<name>.js'|'.cjs'\n` -- stasis-core's source import shape
|
|
2325
|
+
// (`import ... from` / `export ... from`, single-quoted, basename without `.`).
|
|
2326
|
+
// Tight enough to ignore JSDoc / template-literal false positives, narrow enough
|
|
2327
|
+
// to reject parent-relative (`../`), subpath (`./dir/file.js`), or extensionless.
|
|
2328
|
+
// The `.cjs` arm covers state.js -> ./package.cjs (the version re-export shim).
|
|
2329
|
+
for (const m of source.matchAll(/ from '(\.\/[a-zA-Z-]+\.c?js)'\n/g)) recordEdge(m[1])
|
|
2330
|
+
// (2) CJS `require('../package.json')` -- the single CommonJS shim
|
|
2331
|
+
// (src/package.cjs) re-exporting stasis-core's own package.json so state.js can
|
|
2332
|
+
// read its version. Matched exactly (not a general require/`../` relaxation) to
|
|
2333
|
+
// stay as tight as the ESM arm.
|
|
2334
|
+
for (const m of source.matchAll(/require\('(\.\.\/package\.json)'\)/g)) recordEdge(m[1])
|
|
2335
|
+
}
|
|
2336
|
+
}
|
|
2337
|
+
|
|
2338
|
+
// Project-relative files referenced by `this.imports` that the live hooks
|
|
2339
|
+
// didn't capture into this.sources / this.resources, restricted to the
|
|
2340
|
+
// in-scope set (full: everything under state.root; nm: only node_modules).
|
|
2341
|
+
// Out-of-scope files are NOT included -- the live hooks correctly skip them
|
|
2342
|
+
// (workspace files under nm-scope), and including them would force the
|
|
2343
|
+
// backfill caller to wave away false alarms.
|
|
2344
|
+
#collectMissingImportedFiles() {
|
|
2345
|
+
const missing = new Set()
|
|
2346
|
+
for (const [, byParent] of this.imports) {
|
|
2347
|
+
for (const [, specifiers] of byParent) {
|
|
2348
|
+
for (const [, file] of specifiers) {
|
|
2349
|
+
if (typeof file !== 'string') continue
|
|
2350
|
+
if (missing.has(file)) continue
|
|
2351
|
+
// Union of three "captured" signals: hashes (addFile ran -- present
|
|
2352
|
+
// under any lock mode), sources/resources (bundle pre-seeded -- present
|
|
2353
|
+
// under bundle=load even without a lockfile). Any one suffices; a
|
|
2354
|
+
// file in NONE of them is the actual missing-from-capture case.
|
|
2355
|
+
if (this.hashes.has(file) || this.sources.has(file) || this.resources.has(file)) continue
|
|
2356
|
+
const url = pathToFileURL(resolve(this.root, file)).toString()
|
|
2357
|
+
if (!this.config.full && !this.inNodeModules(url)) continue
|
|
2358
|
+
missing.add(file)
|
|
2359
|
+
}
|
|
2360
|
+
}
|
|
2361
|
+
}
|
|
2362
|
+
return missing
|
|
2363
|
+
}
|
|
2364
|
+
}
|
|
2365
|
+
|
|
2366
|
+
// Allowed shape for a backfillable stasis-core path -- a `src/<name>.js` or
|
|
2367
|
+
// `src/<name>.cjs` source, or the package's own `package.json` (required by the
|
|
2368
|
+
// src/package.cjs version shim). Used by the backfill BFS to reject anything that
|
|
2369
|
+
// doesn't look like a real stasis-core file (comment noise, paths escaping `src/`,
|
|
2370
|
+
// etc.). Matched against `/${projectRelativeFile}` so the leading-`/` anchor isn't
|
|
2371
|
+
// fooled by a file at the project root happening to end in `@exodus/stasis-core/...`.
|
|
2372
|
+
// Source basenames are `[a-zA-Z-]+` only -- no `.` in the basename, which is why
|
|
2373
|
+
// `state.util.js` was renamed to `state-util.js`.
|
|
2374
|
+
const STASIS_CORE_FILE_RE = /\/@exodus\/stasis-core\/(?:src\/[a-zA-Z-]+\.c?js|package\.json)$/
|
|
2375
|
+
|