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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/src/loader.js CHANGED
@@ -1,6 +1,4 @@
1
- // stasis-core's run-time loader entry. Evaluating it -- `stasis-core run`, or
2
- // `node --import @exodus/stasis-core/loader` -- snapshots the lib's
3
- // node:fs/path/etc. bindings and registers the module hooks.
1
+ // Run-time loader entry (`node --import @exodus/stasis-core/loader`): evaluating it snapshots the lib's node:fs/path bindings before any patch.
4
2
  import { install } from './hooks.js'
5
3
 
6
4
  install()
package/src/lockfile.js CHANGED
@@ -1,10 +1,8 @@
1
- import { KNOWN_FORMATS, assert, fileMapToObject, fileSetToObject, fromEntries, isPlainObject, posixPathEscapes, sortPaths } from './util.js'
1
+ import { KNOWN_FORMATS, assert, serializeExecutable, fileMapToObject, fileSetToObject, fromEntries, hasNodeModulesSegment, isPlainObject, mergeExecutableSets, mergeFormatMaps, mergeImportMaps, mergeModuleMaps, moduleFileKeys, parseExecutable, posixPathEscapes, sortPaths } from './util.js'
2
2
 
3
3
  const VERSION = 0
4
4
 
5
5
  const normalize = ({ name, version, ecosystem, files }) => {
6
- // `ecosystem` (when present) names the package ecosystem a dependency came from
7
- // (`npm`, `composer`, `soldeer`); the workspace/top-level buckets omit it.
8
6
  assert(ecosystem === undefined || typeof ecosystem === 'string')
9
7
  return { name, version, ...(ecosystem === undefined ? {} : { ecosystem }), files: fromEntries(Object.entries(files)) }
10
8
  }
@@ -16,30 +14,28 @@ export class Lockfile {
16
14
  config
17
15
  entries
18
16
  modules
19
- // Recorded resolutions, mirroring the bundle's `imports` shape:
20
- // conditions key -> parent file -> specifier -> resolved file. `null` (not an
21
- // empty Map) when the lockfile predates resolution attestation -- consumers
22
- // use that to tell "attests no resolutions" apart from "doesn't attest them".
17
+ // conditions -> parent -> specifier -> resolved file. A Map from parse; null only on in-memory constructs that don't attest it.
23
18
  imports
24
- // Recorded loader formats: project-relative file -> Node format string
25
- // (module/commonjs/json/{module,commonjs}-typescript), mirroring the bundle's
26
- // `formats` map. `null` when the lockfile predates format attestation, same
27
- // "attests none" vs "doesn't attest" distinction as `imports`.
19
+ // file -> format string. Same Map/null rule as imports.
28
20
  formats
21
+ // Project-relative paths of attested files carrying a POSIX execute bit, for `stasis extract`. Files only, never a `directory`.
22
+ executable
29
23
 
30
- constructor({ config = { scope: 'full' }, entries, modules, imports, formats } = {}) {
24
+ constructor({ config = { scope: 'full' }, entries, modules, imports, formats, executable } = {}) {
31
25
  assert(['node_modules', 'full'].includes(config.scope))
32
26
  this.config = config
33
27
  this.entries = entries ?? new Set()
34
28
  this.modules = modules ?? new Map()
35
29
  this.imports = imports ?? null
36
30
  this.formats = formats ?? null
31
+ this.executable = executable ?? new Set()
37
32
  }
38
33
 
39
34
  static parse(text) {
40
35
  const json = JSON.parse(text)
41
36
  assert(json.version === VERSION)
42
37
  assert(['node_modules', 'full'].includes(json.config?.scope))
38
+ assert(json.imports !== undefined && json.formats !== undefined, 'lockfile must attest imports and formats')
43
39
 
44
40
  const full = json.config.scope === 'full'
45
41
  assert(!!json.entries === full)
@@ -48,7 +44,7 @@ export class Lockfile {
48
44
 
49
45
  const modules = new Map()
50
46
  for (const [dir, info] of Object.entries(json.modules)) {
51
- assert(dir.includes('node_modules'))
47
+ assert(hasNodeModulesSegment(dir))
52
48
  assert(info?.name && info.version && info.files)
53
49
  modules.set(dir, normalize(info))
54
50
  }
@@ -58,7 +54,7 @@ export class Lockfile {
58
54
  assert(Array.isArray(json.entries))
59
55
  entries = new Set(json.entries)
60
56
  for (const [dir, info] of Object.entries(json.sources)) {
61
- assert(!dir.includes('node_modules'))
57
+ assert(!hasNodeModulesSegment(dir))
62
58
  modules.set(dir, normalize(info))
63
59
  }
64
60
  }
@@ -71,65 +67,55 @@ export class Lockfile {
71
67
  }
72
68
  }
73
69
 
74
- let imports = null
75
- if (json.imports !== undefined) {
76
- assert(isPlainObject(json.imports))
77
- imports = new Map()
78
- for (const [conditions, byParent] of Object.entries(json.imports)) {
79
- assert(isPlainObject(byParent))
80
- const parents = new Map()
81
- for (const [parent, specifiers] of Object.entries(byParent)) {
82
- assert(!posixPathEscapes(parent))
83
- assert(isPlainObject(specifiers))
84
- const specs = new Map()
85
- for (const [specifier, target] of Object.entries(specifiers)) {
86
- // A file string (the common case) or, for a `--metro` multi-platform
87
- // lockfile, a { platform: file } map for an edge that resolves
88
- // differently per platform. Reject any other shape (fail closed).
89
- if (typeof target === 'string') {
90
- assert(!posixPathEscapes(target))
91
- specs.set(specifier, target)
92
- } else {
93
- assert(isPlainObject(target) && Object.keys(target).length > 0,
94
- 'import target must be a file or a non-empty {platform: file} map')
95
- const byPlatform = new Map()
96
- for (const [platform, file] of Object.entries(target)) {
97
- assert(typeof platform === 'string' && platform.length > 0 && !platform.includes('/'), `invalid platform key '${platform}'`)
98
- assert(typeof file === 'string')
99
- assert(!posixPathEscapes(file))
100
- byPlatform.set(platform, file)
101
- }
102
- specs.set(specifier, byPlatform)
70
+ assert(isPlainObject(json.imports))
71
+ const imports = new Map()
72
+ for (const [conditions, byParent] of Object.entries(json.imports)) {
73
+ assert(isPlainObject(byParent))
74
+ const parents = new Map()
75
+ for (const [parent, specifiers] of Object.entries(byParent)) {
76
+ assert(!posixPathEscapes(parent))
77
+ assert(isPlainObject(specifiers))
78
+ const specs = new Map()
79
+ for (const [specifier, target] of Object.entries(specifiers)) {
80
+ if (typeof target === 'string') {
81
+ assert(!posixPathEscapes(target))
82
+ specs.set(specifier, target)
83
+ } else {
84
+ assert(isPlainObject(target) && Object.keys(target).length > 0,
85
+ 'import target must be a file or a non-empty {platform: file} map')
86
+ const byPlatform = new Map()
87
+ for (const [platform, file] of Object.entries(target)) {
88
+ assert(typeof platform === 'string' && platform.length > 0 && !platform.includes('/'), `invalid platform key '${platform}'`)
89
+ assert(typeof file === 'string')
90
+ assert(!posixPathEscapes(file))
91
+ byPlatform.set(platform, file)
103
92
  }
93
+ specs.set(specifier, byPlatform)
104
94
  }
105
- parents.set(parent, specs)
106
95
  }
107
- imports.set(conditions, parents)
96
+ parents.set(parent, specs)
108
97
  }
98
+ imports.set(conditions, parents)
109
99
  }
110
100
 
111
- let formats = null
112
- if (json.formats !== undefined) {
113
- assert(isPlainObject(json.formats))
114
- formats = new Map()
115
- for (const [file, format] of Object.entries(json.formats)) {
116
- assert(!posixPathEscapes(file))
117
- // KNOWN_FORMATS is stasis-core's full universe of recognized formats.
118
- // Rejecting unknowns here -- not at a downstream branch -- means a
119
- // tampered or forward-incompatible lockfile fails closed at the schema
120
- // boundary, with a message that names the offending value.
121
- assert(KNOWN_FORMATS.has(format), `unknown format '${format}' for ${file}`)
122
- // The project root's `directory` listing is keyed '.' -- lockfiles written
123
- // before that normalization keyed it '' (see moduleFileKey), which never
124
- // matches the '.' the hash absorb (join('.', '')) and lookups use. Normalize
125
- // on parse; both keys appearing is a duplicate under the alias -- fail closed.
126
- const key = file === '' ? '.' : file
127
- assert(!formats.has(key), `duplicate format key '${key}'`)
128
- formats.set(key, format)
129
- }
101
+ assert(isPlainObject(json.formats))
102
+ const formats = new Map()
103
+ for (const [file, format] of Object.entries(json.formats)) {
104
+ assert(!posixPathEscapes(file))
105
+ // Reject unknown formats at the schema boundary (not downstream) so a tampered lockfile fails closed.
106
+ assert(KNOWN_FORMATS.has(format), `unknown format '${format}' for ${file}`)
107
+ // '' and '.' alias to the same key (older lockfiles keyed the root listing ''); normalize, fail closed on dupes.
108
+ const key = file === '' ? '.' : file
109
+ assert(!formats.has(key), `duplicate format key '${key}'`)
110
+ formats.set(key, format)
130
111
  }
131
112
 
132
- return new Lockfile({ config: json.config, entries, modules, imports, formats })
113
+ // Every executable must be a file this lockfile attests; the key index is built only when the (usually absent) key is present.
114
+ const executable = json.executable === undefined
115
+ ? new Set()
116
+ : parseExecutable(json.executable, { what: 'lockfile', files: moduleFileKeys(modules), formats, scope: json.config.scope })
117
+
118
+ return new Lockfile({ config: json.config, entries, modules, imports, formats, executable })
133
119
  }
134
120
 
135
121
  serialize() {
@@ -137,7 +123,7 @@ export class Lockfile {
137
123
  const modules = []
138
124
  const sources = []
139
125
  for (const [dir, { name, version, ecosystem, files }] of this.modules) {
140
- const inNodeModules = dir.includes('node_modules')
126
+ const inNodeModules = hasNodeModulesSegment(dir)
141
127
  if (inNodeModules) assert(name && version && files)
142
128
  const type = inNodeModules ? modules : sources
143
129
  const sorted = fromEntries(Object.entries(files).toSorted((a, b) => sortPaths(a[0], b[0])))
@@ -149,10 +135,38 @@ export class Lockfile {
149
135
  const store = { version: this.version, config: this.config }
150
136
  if (this.config.scope === 'full') Object.assign(store, { entries, sources: fromEntries(sources) })
151
137
  Object.assign(store, { modules: fromEntries(modules) })
152
- // Legacy lockfiles (imports/formats === null) round-trip without the key,
153
- // so parse-serialize of an old file stays byte-stable.
154
138
  if (this.imports !== null) Object.assign(store, { imports: fileMapToObject(this.imports) })
155
139
  if (this.formats !== null) Object.assign(store, { formats: fileMapToObject(this.formats) })
140
+ const executable = serializeExecutable(this.executable, {
141
+ what: 'lockfile',
142
+ modules: this.modules,
143
+ // Null on an in-memory construct; an unrecorded format is simply not a directory/stat.
144
+ formats: this.formats ?? new Map(),
145
+ scope: this.config.scope,
146
+ })
147
+ if (executable !== undefined) store.executable = executable
156
148
  return JSON.stringify(store, undefined, 2) + '\n'
157
149
  }
150
+
151
+ // Strict union of two Lockfiles (returns a NEW one): buckets must agree, and a file in both must carry the identical hash (fail closed).
152
+ merge(other) {
153
+ assert(this.config.scope === other.config.scope,
154
+ `lockfile merge: scope mismatch ('${this.config.scope}' vs '${other.config.scope}')`)
155
+ return new Lockfile({
156
+ config: { scope: this.config.scope },
157
+ entries: new Set([...this.entries, ...other.entries]),
158
+ modules: mergeModuleMaps(this.modules, other.modules, 'lockfile merge'),
159
+ imports: mergeNullable(this.imports, other.imports, (a, b) => mergeImportMaps(a, b, 'lockfile merge'), 'imports'),
160
+ formats: mergeNullable(this.formats, other.formats, (a, b) => mergeFormatMaps(a, b, 'lockfile merge'), 'formats'),
161
+ // `other` (the incoming, newer lockfile) wins for the files it records -- see mergeExecutableSets.
162
+ executable: mergeExecutableSets(this.executable, other.executable, other.modules, this.config.scope),
163
+ })
164
+ }
165
+ }
166
+
167
+ const mergeNullable = (a, b, merge, what) => {
168
+ if (a === null && b === null) return null
169
+ assert(a !== null && b !== null,
170
+ `lockfile merge: cannot merge ${what} (one lockfile attests ${what}, the other does not)`)
171
+ return merge(a, b)
158
172
  }
package/src/prune.js CHANGED
@@ -13,16 +13,12 @@ import { basename, dirname, isAbsolute, join, posix, relative, resolve, sep } fr
13
13
 
14
14
  import { Lockfile } from './lockfile.js'
15
15
  import { sha512integrity } from './state-util.js' // also runs the posix-sep assertion
16
- import { isPlainObject, moduleFileKey, posixPathEscapes, splitNodeModulesPath } from './util.js'
16
+ import { hasNodeModulesSegment, isPlainObject, moduleFileKey, posixPathEscapes, splitNodeModulesPath } from './util.js'
17
17
 
18
18
  const LOCKFILE = 'stasis.lock.json'
19
19
 
20
- // Fields we copy (sanitised) from a dependency's on-disk package.json into the
21
- // minimised rewrite. Everything else -- scripts, dependencies, engines, config,
22
- // ... -- is dropped: it isn't recorded in the lockfile, isn't needed to resolve
23
- // or load the package, and (scripts especially) is pure attack surface in an
24
- // installed tree. `name`/`version` are NOT read from disk; they come from the
25
- // lockfile, which is the attested source of the package's identity.
20
+ // Fields copied (sanitised) from a dep's on-disk package.json; everything else is dropped as
21
+ // attack surface (scripts especially).
26
22
  const ROOT_FIELD_ORDER = [
27
23
  'license',
28
24
  'type',
@@ -40,11 +36,7 @@ const ROOT_FIELD_ORDER = [
40
36
  ]
41
37
 
42
38
  function assertGlobalVirtualStoreDisabled() {
43
- // pnpm exports its settings as `npm_config_*` env vars to hooks and
44
- // lifecycle scripts. When the global virtual store is enabled, node_modules
45
- // is dominated by symlinks into a shared store; pruning would walk past
46
- // most files (we skip symlinks) and the lockfile-vs-disk comparison stops
47
- // being meaningful. Reject before touching anything.
39
+ // Global virtual store fills node_modules with symlinks, which prune skips -- lockfile-vs-disk goes blind.
48
40
  const env = process.env.npm_config_enable_global_virtual_store
49
41
  if (env !== undefined && env !== 'false' && env !== '') {
50
42
  throw new Error(
@@ -63,17 +55,12 @@ function buildExpected(lockfile) {
63
55
  const expected = new Map()
64
56
  const knownDirs = new Set()
65
57
  for (const [dir, { files }] of lockfile.modules) {
66
- if (!dir.includes('node_modules')) continue // workspace sources, not pnpm-managed
58
+ if (!hasNodeModulesSegment(dir)) continue // workspace sources, not pnpm-managed
67
59
  knownDirs.add(dir)
68
60
  for (const [rel, hash] of Object.entries(files)) {
69
- // moduleFileKey (not `${dir}/${rel}`): a readdir of a package ROOT records
70
- // rel === '', whose trailing-slash join would miss the `directory` format
71
- // lookup below and wrongly demand a file at `node_modules/<pkg>/`.
61
+ // moduleFileKey, not `${dir}/${rel}`: a root capture's rel === '' would demand a file at `<pkg>/`.
72
62
  const file = moduleFileKey(dir, rel)
73
- // A `directory` entry (`stasis run --fs` readdir capture) is a JSON listing
74
- // attested by hash, NOT a file on disk -- the on-disk path is a real directory
75
- // whose contents prune walks separately. Excluding it keeps prune from
76
- // demanding a regular file at the directory's path ("missing on disk").
63
+ // A `directory` entry is an attested listing, not a file on disk; demanding one would fail "missing on disk".
77
64
  if (lockfile.formats?.get(file) === 'directory') continue
78
65
  expected.set(file, hash)
79
66
  }
@@ -81,29 +68,19 @@ function buildExpected(lockfile) {
81
68
  return { expected, knownDirs }
82
69
  }
83
70
 
84
- // True when `ref` (a package.json file reference like "./a.js", "a/b", "./dir")
85
- // names a file the lockfile records for this module, so a rewritten manifest
86
- // never points resolution at a path prune is about to delete. A ref that
87
- // escapes the module (`..`/absolute) is rejected outright -- it can never name a
88
- // recorded file. A subpath pattern ("./*") can't be enumerated against a fixed
89
- // file list, but the only files left after prune are the attested ones -- so a
90
- // (non-escaping) pattern can only ever resolve onto an attested file -- and it's
91
- // kept as-is. `exact` selects the resolution discipline for a concrete path:
92
- // exports/imports targets are matched verbatim (Node applies no CommonJS
93
- // extension/index resolution to them), whereas main/module/browser/bin get the
94
- // legacy expansion (`main: "lib"` -> `lib/index.js`).
71
+ // A rewritten manifest must never point resolution at a path prune is about to delete.
95
72
  const EXTENSIONS = ['.js', '.cjs', '.mjs', '.json', '.node']
96
73
 
97
74
  function normalizeRef(ref) {
98
75
  if (typeof ref !== 'string' || ref === '') return null
99
- if (posixPathEscapes(ref)) return null // leading/embedded `..` above root, or absolute
76
+ if (posixPathEscapes(ref)) return null
100
77
  return posix.normalize(ref).replace(/^\.\//u, '')
101
78
  }
102
79
 
103
80
  function referencesPresentFile(ref, present, { exact = false } = {}) {
104
81
  const base = normalizeRef(ref)
105
- if (base === null) return false // non-string, empty, escaping, or absolute
106
- if (base.includes('*')) return true // subpath pattern: unverifiable, kept (see above)
82
+ if (base === null) return false
83
+ if (base.includes('*')) return true // subpath pattern: unverifiable, kept
107
84
  if (present.has(base)) return true
108
85
  if (exact) return false // exports/imports targets resolve verbatim -- no extension/index fallback
109
86
  for (const ext of EXTENSIONS) if (present.has(base + ext)) return true
@@ -111,21 +88,10 @@ function referencesPresentFile(ref, present, { exact = false } = {}) {
111
88
  return false
112
89
  }
113
90
 
114
- // Real exports/imports trees nest only a few conditions deep; anything past this
115
- // is a malformed or hostile manifest. We cap the recursion (rather than risk a
116
- // stack overflow that would abort the whole prune and leave the offending
117
- // package's unattested files in place) and drop the over-deep subtree.
91
+ // Cap the recursion; real exports/imports trees nest a few deep and a deep one must not overflow.
118
92
  const MAX_TARGET_DEPTH = 64
119
93
 
120
- // Recursively filter an exports/imports/browser subtree down to the mappings
121
- // whose targets are still present. `allowBare` keeps bare specifiers (imports
122
- // may map "#x" to another package; browser may stub/redirect a bare module);
123
- // `allowFalse` keeps `false` (browser/react-native module stubbing); `exact` is
124
- // passed through to referencesPresentFile (exports/imports match verbatim). A
125
- // `null` target (exports/imports blocking a subpath) is always kept. An object
126
- // or array that filters down to nothing is dropped, so we never emit an empty
127
- // `exports: {}` -- which would block every subpath rather than fall back to
128
- // `main`.
94
+ // An object/array filtering to empty is dropped: `exports: {}` would block every subpath instead of `main`.
129
95
  function filterTargets(value, present, opts, depth = 0) {
130
96
  if (depth > MAX_TARGET_DEPTH) return { keep: false }
131
97
  const { allowBare, allowFalse, exact } = opts
@@ -160,13 +126,10 @@ function filterTargets(value, present, opts, depth = 0) {
160
126
  return { keep: false }
161
127
  }
162
128
 
163
- // Printable ASCII only: rejects the C0 (incl. DEL) and C1 control ranges and all
164
- // non-ASCII, so a copied `license` can't smuggle control or escape characters.
129
+ // Printable ASCII only, so a copied `license` can't smuggle control or escape characters.
165
130
  const isAscii = (s) => /^[\x20-\x7e]*$/u.test(s)
166
131
 
167
- // `browser`/`react-native`: a string (an alternate entry, like `main`) or a map
168
- // of source path / bare module -> replacement file or `false` (stub). Returns
169
- // the filtered value, or undefined to drop the field.
132
+ // `browser`/`react-native`: a string, or a map to replacements/`false`. undefined means drop the field.
170
133
  function browserField(value, present) {
171
134
  if (typeof value === 'string') return referencesPresentFile(value, present) ? value : undefined
172
135
  if (isPlainObject(value)) {
@@ -176,28 +139,17 @@ function browserField(value, present) {
176
139
  return undefined
177
140
  }
178
141
 
179
- // The fields that govern how a package's own files resolve and load: the module
180
- // system flag (`type`), the entry points (`main`/`module`/`browser`/
181
- // `react-native`), and the subpath maps (`exports`/`imports`). Shared by the
182
- // package root and by nested markers -- a nested marker is exactly this subset.
183
- // Every file reference is filtered to a present (attested) file: exports/imports
184
- // match verbatim (`exact`), the entry fields get Node's extension/index expansion.
142
+ // Resolution fields (`type`, entry points, exports/imports), every file reference filtered to an attested file.
185
143
  function resolutionFields(pkg, present) {
186
144
  const out = { __proto__: null }
187
145
 
188
- // Only the two values Node honours; a flipped/garbage `type` is dropped so it
189
- // falls back to the default rather than recategorising the package's .js files.
146
+ // Only the values Node honours; a garbage `type` is dropped rather than recategorising the package's .js files.
190
147
  if (pkg.type === 'module' || pkg.type === 'commonjs') out.type = pkg.type
191
148
 
192
149
  if (referencesPresentFile(pkg.main, present)) out.main = pkg.main
193
- // `module`: non-standard ESM entry that bundlers (webpack/rollup/esbuild)
194
- // prefer over `main`; kept on the same "points at a present file" basis.
195
150
  if (referencesPresentFile(pkg.module, present)) out.module = pkg.module
196
151
 
197
- // Legacy / framework entry points read via bundler `mainFields`: `jsnext:main`
198
- // and `jsnext` (in Vite's default list -- dropping them downgrades an older
199
- // dep ESM->CJS under Vite) and `source` (Parcel, Metro/React Native). String
200
- // entries, kept like main/module; inert for resolvers that don't read them.
152
+ // Bundler `mainFields` entries: dropping jsnext/jsnext:main downgrades an older dep ESM->CJS under Vite.
201
153
  for (const field of ['jsnext:main', 'jsnext', 'source']) {
202
154
  if (referencesPresentFile(pkg[field], present)) out[field] = pkg[field]
203
155
  }
@@ -215,23 +167,14 @@ function resolutionFields(pkg, present) {
215
167
  return out
216
168
  }
217
169
 
218
- // Compute the sanitised field set for a package *root* package.json (the dir is
219
- // a module the lockfile records). `name`/`version` are authoritative from the
220
- // lockfile; the rest are copied from `pkg` (the untrusted on-disk manifest)
221
- // only after passing their field-specific guard. On top of the shared
222
- // resolution fields, a root also carries `license` and the package-level
223
- // `bin`/`sideEffects`.
170
+ // On-disk `pkg` is untrusted: every copied field needs its own guard. name/version come from the lockfile.
224
171
  function minimalRootFields(pkg, { name, version, present }) {
225
172
  const fields = resolutionFields(pkg, present)
226
173
 
227
- // A short, plain-ASCII license string is harmless metadata; anything else
228
- // (object/array SPDX forms, long or non-ASCII blobs) is dropped.
229
174
  if (typeof pkg.license === 'string' && isAscii(pkg.license) && Buffer.byteLength(pkg.license) < 64) {
230
175
  fields.license = pkg.license
231
176
  }
232
177
 
233
- // bin: a string (one command, named after the package) or a map of
234
- // command -> file. Keep only entries that point at a present file.
235
178
  if (typeof pkg.bin === 'string') {
236
179
  if (referencesPresentFile(pkg.bin, present)) fields.bin = pkg.bin
237
180
  } else if (isPlainObject(pkg.bin)) {
@@ -246,10 +189,7 @@ function minimalRootFields(pkg, { name, version, present }) {
246
189
  if (any) fields.bin = bin
247
190
  }
248
191
 
249
- // sideEffects: a boolean is kept verbatim; an array is filtered to entries
250
- // that are present files (glob patterns are kept, see referencesPresentFile).
251
- // A list that filters to empty is dropped rather than emitted as `[]`, which
252
- // would assert "no side effects" and over-eagerly tree-shake.
192
+ // A sideEffects list filtering to empty is dropped: `[]` would assert "no side effects" and over-tree-shake.
253
193
  if (typeof pkg.sideEffects === 'boolean') {
254
194
  fields.sideEffects = pkg.sideEffects
255
195
  } else if (Array.isArray(pkg.sideEffects)) {
@@ -257,41 +197,24 @@ function minimalRootFields(pkg, { name, version, present }) {
257
197
  if (se.length > 0) fields.sideEffects = se
258
198
  }
259
199
 
260
- // name/version first, then the copied fields in a stable order.
261
200
  const out = { name, version }
262
201
  for (const key of ROOT_FIELD_ORDER) if (key in fields) out[key] = fields[key]
263
202
  return out
264
203
  }
265
204
 
266
- // A nested package.json (e.g. a `dist/cjs/package.json` that flips the module
267
- // system for that subtree) carries no package identity, so we drop name/version
268
- // and the package-level fields (license/bin/sideEffects) and keep exactly the
269
- // resolution fields, filtered relative to this dir. Dropping them outright -- as
270
- // the old prune did, since their dir isn't a recorded module and they aren't in
271
- // the lockfile file list -- would silently revert this subtree's .js files to
272
- // the package root's module system and break `require('pkg/subdir')` and
273
- // `#imports` resolution within it.
205
+ // A nested package.json flips its subtree's module system; dropping it would revert those .js files to the root's.
274
206
  function minimalNestedFields(pkg, present) {
275
207
  return resolutionFields(pkg, present)
276
208
  }
277
209
 
278
210
  const PNPM_WORKSPACE = 'pnpm-workspace.yaml'
279
211
 
280
- // A pnpm workspace root is marked by a pnpm-workspace.yaml. In a workspace,
281
- // prune covers every package's node_modules (not just the root's) and widens
282
- // the symlink-containment boundary from node_modules to the whole workspace --
283
- // a workspace dependency legitimately links to a sibling package's source dir,
284
- // which lives outside any node_modules but inside the workspace. Outside a
285
- // workspace the boundary stays at node_modules (a self-contained install must
286
- // not reach beyond it).
212
+ // In a workspace the symlink-containment boundary widens from node_modules to the whole workspace,
213
+ // since a dep legitimately links to a sibling package's source dir.
287
214
  function isPnpmWorkspaceRoot(root) {
288
215
  return existsSync(join(root, PNPM_WORKSPACE))
289
216
  }
290
217
 
291
- // Every node_modules directory in the workspace (the root's and each package's).
292
- // We don't descend into a node_modules once found -- prune walks its internals
293
- // itself -- nor into dotdirs (.git, ...), and we never leave `root` (symlinked
294
- // dirs that aren't node_modules aren't followed).
295
218
  function discoverNodeModulesDirs(root) {
296
219
  const found = []
297
220
  const stack = [root]
@@ -304,46 +227,31 @@ function discoverNodeModulesDirs(root) {
304
227
  continue
305
228
  }
306
229
  for (const entry of entries) {
307
- if (entry.name.startsWith('.')) continue // .git, .pnpm-* state, other dotdirs
230
+ if (entry.name.startsWith('.')) continue
308
231
  const full = join(dir, entry.name)
309
232
  if (entry.name === 'node_modules') {
310
- // Only a real node_modules dir is a prune target. A package whose
311
- // node_modules is itself a symlink is skipped here (not a real pnpm
312
- // layout); if the lockfile records files under it, prune fails closed
313
- // ("missing on disk") rather than walking through the link.
233
+ // A symlinked node_modules is skipped; if the lockfile records files under it, prune fails closed.
314
234
  if (entry.isDirectory()) found.push(full)
315
235
  continue // don't descend; prune walks node_modules internals itself
316
236
  }
317
- if (entry.isDirectory()) stack.push(full) // a workspace source dir: keep looking
237
+ if (entry.isDirectory()) stack.push(full)
318
238
  }
319
239
  }
320
240
  return found
321
241
  }
322
242
 
323
- // A symlink is left in place only if its real target stays inside `boundary`
324
- // (`label` names it in the error): node_modules for a self-contained install,
325
- // or the whole workspace when pruning a pnpm workspace. That boundary is prune's
326
- // containment perimeter -- a link reaching outside it would keep bytes prune
327
- // never walks reachable from the pruned tree. pnpm's public `node_modules/<pkg>`
328
- // links into `.pnpm`, whose real bytes are walked directly, so the link needs no
329
- // validation or deletion; in a workspace a dep also links to a sibling source
330
- // dir (inside the workspace, outside any node_modules), which is left as-is and
331
- // not validated. An escaping link fails closed; because this runs during the
332
- // planning walk, before any unlink/rewrite, it aborts prune without touching
333
- // disk. A dangling link points at nothing and can't leak, so it's left as-is.
334
- //
335
- // (Deliberately NOT the loaders' assertRealPathWithinBase: it rethrows ENOENT,
336
- // whereas here a dangling link is tolerated.)
243
+ // A symlink survives prune only if its real target stays inside `boundary`. A dangling link can't leak,
244
+ // so ENOENT returns instead of throwing -- deliberately NOT the loaders' assertRealPathWithinBase.
337
245
  function assertSymlinkInternal({ root, realBoundary, label }, linkPath) {
338
246
  let real
339
247
  try {
340
248
  real = realpathSync(linkPath)
341
249
  } catch (err) {
342
- if (err.code === 'ENOENT') return // dangling link
250
+ if (err.code === 'ENOENT') return
343
251
  throw err
344
252
  }
345
253
  const rel = relative(realBoundary, real)
346
- if (rel === '' || (!rel.startsWith('..') && !isAbsolute(rel))) return // inside the boundary
254
+ if (rel === '' || (!rel.startsWith('..') && !isAbsolute(rel))) return
347
255
  throw new Error(`stasis prune: symlink escapes ${label}: ${relative(root, linkPath)} -> ${real}`)
348
256
  }
349
257
 
@@ -364,8 +272,7 @@ function* walkFiles(nmRoot, ctx) {
364
272
  }
365
273
  }
366
274
 
367
- // Walk every node_modules root, tagging each file with the root it came from so
368
- // deletion and empty-dir pruning stay scoped to that node_modules.
275
+ // Tag each file with its node_modules root so deletion and empty-dir pruning stay scoped to it.
369
276
  function* walkAll(nmRoots, ctx) {
370
277
  for (const nmRoot of nmRoots) {
371
278
  for (const full of walkFiles(nmRoot, ctx)) yield { full, nmRoot }
@@ -393,9 +300,6 @@ function pruneEmptyDirs(dir, stopAt) {
393
300
  export function prune({ root = process.cwd() } = {}) {
394
301
  assertGlobalVirtualStoreDisabled()
395
302
  root = resolve(root)
396
- // In a pnpm workspace, prune every package's node_modules (not just the
397
- // root's) and bound symlinks by the whole workspace; otherwise just the root's
398
- // node_modules, bounded by node_modules itself.
399
303
  const workspace = isPnpmWorkspaceRoot(root)
400
304
  const nmRoots = workspace ? discoverNodeModulesDirs(root) : [join(root, 'node_modules')]
401
305
  const boundary = workspace ? root : join(root, 'node_modules')
@@ -407,10 +311,7 @@ export function prune({ root = process.cwd() } = {}) {
407
311
  const lockfile = loadLockfile(root)
408
312
  const { expected, knownDirs } = buildExpected(lockfile)
409
313
 
410
- // Plan first, mutate later: walk the tree, validate every tracked file,
411
- // collect the deletion and package.json-rewrite lists, and verify nothing in
412
- // the lockfile is missing. Bail with a thrown error before touching disk on
413
- // any failure.
314
+ // Plan first, mutate later: any failure throws before anything on disk is touched.
414
315
  const toRemove = []
415
316
  const toMinimize = []
416
317
  const validated = []
@@ -433,12 +334,7 @@ export function prune({ root = process.cwd() } = {}) {
433
334
  continue
434
335
  }
435
336
 
436
- // package.json files aren't enumerated in the lockfile (their contents
437
- // aren't recorded), but they're load-bearing for resolution, so rather than
438
- // keep them verbatim we rewrite them down to the minimal, lockfile-derived
439
- // field set when they belong to a module the lockfile recognises. A
440
- // package.json that IS in the lockfile (imported directly, so its bytes are
441
- // attested) took the hash-validated branch above and is kept in full.
337
+ // package.json isn't lockfile-enumerated but drives resolution, so rewrite (not delete) it for a known module.
442
338
  if (basename(rel) === 'package.json') {
443
339
  const owner = splitNodeModulesPath(rel)
444
340
  if (owner && knownDirs.has(owner.dir)) {
@@ -453,13 +349,11 @@ export function prune({ root = process.cwd() } = {}) {
453
349
  let next
454
350
  if (dirname(rel) === owner.dir) {
455
351
  const { name, version, files } = lockfile.modules.get(owner.dir)
456
- // The package.json itself survives prune, so it's always a legal
457
- // self-reference target (e.g. `exports: { "./package.json": ... }`).
352
+ // The package.json itself survives prune, so it's always a legal self-reference target.
458
353
  const present = new Set([...Object.keys(files), 'package.json'])
459
354
  next = minimalRootFields(pkg, { name, version, present })
460
355
  } else {
461
- // A nested package.json's file references are relative to its own
462
- // dir, so re-base the module's recorded files onto it before filtering.
356
+ // A nested package.json's refs are relative to its own dir, so re-base the recorded files first.
463
357
  const { files } = lockfile.modules.get(owner.dir)
464
358
  const prefix = `${relative(owner.dir, dirname(rel))}/`
465
359
  const present = new Set(['package.json'])
@@ -473,13 +367,9 @@ export function prune({ root = process.cwd() } = {}) {
473
367
  if (newText !== raw) toMinimize.push({ full, rel, text: newText })
474
368
  continue
475
369
  }
476
- // package.json under a dir the lockfile doesn't own falls through and is
477
- // pruned like any other untracked file.
478
370
  }
479
371
 
480
- // Defense-in-depth: the path must resolve inside the node_modules we're
481
- // walking (no symlink escape, no `..` traversal) before we queue it for
482
- // deletion -- so prune never deletes anything outside a node_modules.
372
+ // Defense-in-depth: the walk should already guarantee this.
483
373
  assert.ok(
484
374
  full.startsWith(`${nmRoot}${sep}`),
485
375
  `refusing to remove path outside node_modules: ${full}`,
@@ -505,12 +395,7 @@ export function prune({ root = process.cwd() } = {}) {
505
395
 
506
396
  const minimized = []
507
397
  for (const [i, { full, rel, text }] of toMinimize.entries()) {
508
- // Replace, never modify in place: a dependency's package.json is commonly a
509
- // hardlink into pnpm's content-addressable store, so it shares an inode with
510
- // every other project (and other versions) linked from that store. An
511
- // in-place write would mutate all of them. Write a fresh file and rename it
512
- // over the entry -- atomic, and it breaks the hardlink, leaving the store
513
- // copy untouched.
398
+ // Write+rename, never in place: a dep's package.json is often a hardlink into pnpm's store (shared inode).
514
399
  const tmp = `${full}.stasis-${process.pid}-${i}.tmp`
515
400
  writeFileSync(tmp, text)
516
401
  renameSync(tmp, full)