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

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.
@@ -0,0 +1,679 @@
1
+ // The pure half of the util split: the artifact data model shared by bundle.js, lockfile.js and
2
+ // shard.js (the format universe, flat file keys, strict merges, the executable-set rules and the
3
+ // JSON<->Map converters). No Node builtin imports, so `./bundle` and `./lockfile` load in any JS
4
+ // runtime. util.js re-exports this module, so `@exodus/stasis-core/util` serves the full set.
5
+
6
+ // KNOWN_FORMATS is the closed universe of `format` strings; parsers reject anything outside it.
7
+ export const NODE_FORMATS = new Set(['module', 'commonjs', 'json', 'module-typescript', 'commonjs-typescript'])
8
+ export const SOURCE_LANGUAGE_FORMATS = new Set(['solidity', 'php', 'shell', 'rust'])
9
+ export const NATIVE_BUILD_FORMATS = new Set([
10
+ 'java', 'kotlin', 'gradle', 'objc', 'objcpp', 'swift', 'c', 'cpp', 'c-header', 'cpp-header',
11
+ 'ruby', 'python', 'cmake', 'podspec', 'podfile', 'podfile-lock', 'template', 'xml', 'env', 'fastlane', 'pbxproj',
12
+ ])
13
+ export const RESOURCE_FORMATS = new Set(['resource', 'resource:base64'])
14
+ export const STAT_FORMATS = new Set(['stat:file', 'stat:directory'])
15
+ export const KNOWN_FORMATS = new Set([
16
+ ...NODE_FORMATS,
17
+ ...SOURCE_LANGUAGE_FORMATS,
18
+ ...NATIVE_BUILD_FORMATS,
19
+ ...RESOURCE_FORMATS,
20
+ 'patch', // a `.patch` unified diff (pnpm patchedDependencies, patch-package): UTF-8 text applied by a patch step
21
+ 'directory',
22
+ ...STAT_FORMATS,
23
+ ])
24
+
25
+ // Payload-free stat records: attest a path's KIND, no content, and yield to a real format.
26
+ export const isStatFormat = (format) => STAT_FORMATS.has(format)
27
+
28
+ // Reserved synthetic file a disabled import (a `browser`/`react-native` field mapping it to `false`)
29
+ // points at: never on disk, carried as empty CommonJS so the edge resolves to attested bytes.
30
+ export const EMPTY_MODULE_PATH = '.stasis/empty-module.js'
31
+
32
+ // The post-erasure family of a '-typescript' loader format ('module-typescript' -> 'module'): a
33
+ // transforming preload (`stasis run --import tsx`) resolves/serves a TypeScript file as the JS
34
+ // family it transpiles to, while the attestation keeps the on-disk format. undefined otherwise.
35
+ export const erasedTypeScriptFormat = (format) =>
36
+ format === 'module-typescript' ? 'module' : format === 'commonjs-typescript' ? 'commonjs' : undefined
37
+
38
+ const formatKind = (format) => (format === 'directory' || format === 'stat:directory' ? 'directory' : 'file')
39
+
40
+ // A weak 'stat:*' yields to a real format of the SAME kind and never displaces one; anything else throws.
41
+ export function reconcileFormat(format, currentFormat, name) {
42
+ if (format === currentFormat) return format
43
+ const stat = isStatFormat(format)
44
+ if (stat !== isStatFormat(currentFormat) && formatKind(format) === formatKind(currentFormat)) {
45
+ return stat ? currentFormat : format
46
+ }
47
+ throw new Error(`format conflict for '${name}' ('${currentFormat}' vs '${format}')`)
48
+ }
49
+
50
+ // Flat project-relative key. `rel === ''` (a `directory` capture whose path IS a module root) keys the
51
+ // bare dir, never `${dir}/` -- a trailing slash breaks the round-trip.
52
+ export function moduleFileKey(dir, rel) {
53
+ if (rel === '') return dir
54
+ return dir === '.' ? rel : `${dir}/${rel}`
55
+ }
56
+
57
+ // GitHub `owner/name` (owner 1-39, name 1-100 chars).
58
+ const GITHUB_REPO = /^(?=[A-Za-z0-9-]{1,39}\/)[A-Za-z0-9](?:-?[A-Za-z0-9])*\/(?!\.\.?$)[\w.-]{1,100}$/u
59
+ // Non-empty normalized repo-relative path of URL-safe segments.
60
+ const REPO_DIRECTORY = /^(?!\.\.?(?:\/|$))[\w.~@+-]+(?:\/(?!\.\.?(?:\/|$))[\w.~@+-]+)*$/u
61
+ // Full lowercase SHA-1 or SHA-256.
62
+ const GIT_SHA = /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/u
63
+ // The fields of a `repo`, the bundle's own or a dependency's, and their checks.
64
+ export const REPO_FIELDS = {
65
+ github: (v) => typeof v === 'string' && GITHUB_REPO.test(v),
66
+ // `''` is the repository's root.
67
+ directory: (v) => typeof v === 'string' && v.length <= 1024 && (v === '' || REPO_DIRECTORY.test(v)),
68
+ commit: (v) => typeof v === 'string' && GIT_SHA.test(v),
69
+ }
70
+
71
+ // Whether two GitHub `owner/name`s are one: GitHub's names are case-insensitive.
72
+ export const sameGithub = (a, b) => a?.toLowerCase() === b?.toLowerCase()
73
+
74
+ // Whether two `repo`s name the same place: every field alike, `github` in any case.
75
+ export const sameRepo = (a, b) => Object.keys(REPO_FIELDS).every((key) => (key === 'github' ? sameGithub(a.github, b.github) : a[key] === b[key]))
76
+
77
+ // Whether two records of one dependency agree on its `repo`: an artifact from before the field records none.
78
+ export const reposAgree = (a, b) => a === undefined || b === undefined || sameRepo(a, b)
79
+
80
+ // Validate a block against its `fields` (each optional: a check, or a nested block's fields), `what`
81
+ // naming it in errors; canonical, frozen, undefined if empty. Messages are built on failure alone: a
82
+ // dependency's `repo` is checked on every parse and write.
83
+ export const normalizeBlock = (block, fields, what) => {
84
+ if (block === undefined) return undefined
85
+ if (!isPlainObject(block)) assert(false, `${what} must be an object`)
86
+ for (const key of Object.keys(block)) if (!Object.hasOwn(fields, key)) assert(false, `unknown ${what} key '${key}'`)
87
+ const entries = Object.entries(fields).map(([key, check]) => {
88
+ if (typeof check === 'object') return [key, normalizeBlock(block[key], check, `${what}.${key}`)]
89
+ if (block[key] !== undefined && !check(block[key])) assert(false, `invalid ${what}.${key}: ${JSON.stringify(block[key])}`)
90
+ return [key, block[key]]
91
+ }).filter(([, value]) => value !== undefined)
92
+ return entries.length === 0 ? undefined : Object.freeze(fromEntries(entries))
93
+ }
94
+
95
+ // Validate a `repo` (all fields optional); canonical key order, undefined if empty.
96
+ export const normalizeRepo = (repo, what = 'bundle repo') => normalizeBlock(repo, REPO_FIELDS, what)
97
+
98
+ // A bucket's ecosystem as a dependency's: its `ecosystem` tag, or npm for an untagged one under
99
+ // node_modules (an artifact from before the tag); undefined for first-party code.
100
+ export const dependencyEcosystem = (dir, ecosystem) => ecosystem ?? (hasNodeModulesSegment(dir) ? 'npm' : undefined)
101
+
102
+ // A dependency's `repo`, the one its own manifest names, with the bundle's own fields, `github`
103
+ // required: a `directory` or `commit` places nothing without the repository it is in. First-party
104
+ // code carries none.
105
+ const normalizeModuleRepo = (dir, { ecosystem, repo }, what) => {
106
+ if (repo === undefined) return undefined
107
+ if (dependencyEcosystem(dir, ecosystem) === undefined) assert(false, `${what}: '${dir}' is no dependency's bucket, and carries no repo`)
108
+ const normalized = normalizeRepo(repo, `${what} module '${dir}' repo`)
109
+ if (normalized?.github === undefined) assert(false, `${what} module '${dir}' repo has no github`)
110
+ return normalized
111
+ }
112
+
113
+ // A package name or version: characters some ecosystem uses there (npm's legacy `~'!()*` too), so not space or `"#$%&,:;<=>?[\]^`{|}`.
114
+ export const isPackageString = (v) => typeof v === 'string' && /^[\w.+@/~'!()*-]+$/u.test(v)
115
+ export const PACKAGE_BLOCK = { name: isPackageString, version: isPackageString }
116
+
117
+ // A directory key of a record's `vendored` or `subpackages`: an in-bucket path in canonical form, through
118
+ // no `node_modules` (a package installed there is a bucket of its own).
119
+ const isBucketDir = (dir) => typeof dir === 'string' && dir !== '' && !dir.includes('\\') &&
120
+ dir.split('/').every((segment) => segment !== '' && segment !== '.' && segment !== '..' && segment !== 'node_modules')
121
+
122
+ // Whether a package.json naming `manifestName`, at `dir` (package-relative, POSIX) inside the package named
123
+ // `hostName`, is one of its subpackages: a subpath entry point with a package.json of its own, named in
124
+ // the package's namespace for the very directory it is in (`@hookform/resolvers/zod` at zod/), as
125
+ // microbundle lays them out. It is the package's own code, and its `version`, a placeholder (1.0.0), its
126
+ // own: held to nothing.
127
+ export const isSubpackage = (manifestName, hostName, dir) =>
128
+ typeof manifestName === 'string' && isBucketDir(dir) && manifestName === `${hostName}/${dir}`
129
+
130
+ // A record's per-directory metadata, each entry the `name` (required) and `version` of the package.json in
131
+ // that directory: `vendored`, the packages copied into a dependency (any name), and `subpackages`, its own
132
+ // subpath entry points (isSubpackage).
133
+ const DIR_METADATA = {
134
+ vendored: () => true,
135
+ subpackages: (entry, name, sub) => isSubpackage(entry.name, name, sub),
136
+ }
137
+
138
+ // The directory of `entries` a bucket file `rel` is in: the deepest one listed that holds it.
139
+ const entryDirOf = (entries, rel) => {
140
+ for (let slash = rel.lastIndexOf('/'); slash > 0; slash = rel.lastIndexOf('/', slash - 1)) {
141
+ if (Object.hasOwn(entries, rel.slice(0, slash))) return rel.slice(0, slash)
142
+ }
143
+ return undefined
144
+ }
145
+
146
+ // The entries of a `vendored` or `subpackages` that hold one of `files`, each file counted for the deepest
147
+ // entry holding it; path-sorted and frozen, undefined if none. An artifact lists those it carries a file of.
148
+ function carriedEntries(entries, files) {
149
+ if (entries === undefined) return undefined
150
+ const carried = new Set()
151
+ for (const rel of Object.keys(files)) {
152
+ const dir = entryDirOf(entries, rel)
153
+ if (dir !== undefined) carried.add(dir)
154
+ }
155
+ return carried.size === 0 ? undefined : Object.freeze(fromEntries([...carried].toSorted(sortPaths).map((dir) => [dir, entries[dir]])))
156
+ }
157
+
158
+ // A dependency's `field` of DIR_METADATA, validated: each entry holds one of the record's `files`. First-party
159
+ // code carries none.
160
+ const normalizeDirMetadata = (field, dir, { name, ecosystem, files, [field]: entries }, what) => {
161
+ if (entries === undefined) return undefined
162
+ if (dependencyEcosystem(dir, ecosystem) === undefined) assert(false, `${what}: '${dir}' is no dependency's bucket, and carries no ${field}`)
163
+ if (!isPlainObject(entries)) assert(false, `${what} module '${dir}' ${field} must be an object`)
164
+ const normalized = fromEntries(Object.entries(entries).map(([sub, block]) => {
165
+ if (!isBucketDir(sub)) assert(false, `${what} module '${dir}' ${field}: invalid directory ${JSON.stringify(sub)}`)
166
+ const entry = normalizeBlock(block, PACKAGE_BLOCK, `${what} module '${dir}' ${field} '${sub}'`)
167
+ if (entry?.name === undefined) assert(false, `${what} module '${dir}' ${field} '${sub}' has no name`)
168
+ if (!DIR_METADATA[field](entry, name, sub)) assert(false, `${what} module '${dir}' ${field} '${sub}' is named '${entry.name}', not '${name}/${sub}'`)
169
+ return [sub, entry]
170
+ }))
171
+ const carried = carriedEntries(normalized, files)
172
+ for (const sub of Object.keys(normalized)) {
173
+ if (!Object.hasOwn(carried ?? {}, sub)) assert(false, `${what} module '${dir}' ${field} '${sub}' holds none of its files`)
174
+ }
175
+ return carried
176
+ }
177
+
178
+ // A module bucket record in canonical key order; `ecosystem`, `repo`, `vendored` and `subpackages` are omitted (not undefined) when absent.
179
+ export const moduleInfo = ({ name, version, ecosystem, repo, vendored, subpackages, files }) => ({
180
+ name, version,
181
+ ...(ecosystem === undefined ? {} : { ecosystem }),
182
+ ...(repo === undefined ? {} : { repo }),
183
+ ...(vendored === undefined ? {} : { vendored }),
184
+ ...(subpackages === undefined ? {} : { subpackages }),
185
+ files,
186
+ })
187
+
188
+ // `record` with the metadata `other` (of the same bucket) has and it lacks: `repo` where it records none,
189
+ // the `vendored` and `subpackages` entries of directories it lists none for. Metadata is held to nothing,
190
+ // so where both record one, `record`'s stands. `record` itself when that adds nothing.
191
+ export function withMetadataOf(record, other) {
192
+ const repo = record.repo ?? other.repo
193
+ const fields = Object.keys(DIR_METADATA).filter((field) =>
194
+ other[field] !== undefined && Object.keys(other[field]).some((sub) => !Object.hasOwn(record[field] ?? {}, sub)))
195
+ if (repo === record.repo && fields.length === 0) return record
196
+ const merged = fromEntries(fields.map((field) => [field, Object.freeze(fromEntries([...Object.entries(other[field]), ...Object.entries(record[field] ?? {})]))]))
197
+ return moduleInfo({ ...record, repo, ...merged })
198
+ }
199
+
200
+ // A record's `vendored` and `subpackages` as `what` writes them: the entries holding one of `files`, validated;
201
+ // a field not in `fields` left out.
202
+ const carriedDirMetadata = (dir, info, files, what, fields) => fromEntries(Object.keys(DIR_METADATA).map((field) =>
203
+ [field, fields.includes(field) ? normalizeDirMetadata(field, dir, { ...info, files, [field]: carriedEntries(info[field], files) }, what) : undefined]))
204
+
205
+ // The packages a module map records, for what looks at each of them (`stasis audit`): every record, as it is,
206
+ // and after a dependency's, each `vendored` copy in it as a record of its own, at the copy's directory in the
207
+ // project (`node_modules/next/dist/compiled/react-is`): its `name` and `version`, its host's `ecosystem`,
208
+ // `vendoredIn` its host's dir, and `files`, those the copy holds (each counted for the deepest entry holding
209
+ // it), relative to that directory. A host keeps all its files, the copies' too: they are shipped as its.
210
+ // File values are carried over as they are (a contents-free bundle's locked ones unread).
211
+ export function* packageRecords(modules) {
212
+ for (const [dir, record] of modules) {
213
+ yield [dir, record]
214
+ if (record.vendored === undefined) continue
215
+ const held = new Map()
216
+ for (const rel of Object.keys(record.files)) {
217
+ const sub = entryDirOf(record.vendored, rel)
218
+ if (sub === undefined) continue
219
+ if (!held.has(sub)) held.set(sub, Object.create(null))
220
+ Object.defineProperty(held.get(sub), rel.slice(sub.length + 1), Object.getOwnPropertyDescriptor(record.files, rel))
221
+ }
222
+ for (const [sub, files] of held) {
223
+ const { name, version } = record.vendored[sub]
224
+ yield [moduleFileKey(dir, sub), { name, version, ecosystem: record.ecosystem, vendoredIn: dir, files }]
225
+ }
226
+ }
227
+ }
228
+
229
+ // A parsed bucket `dir` of a `what` artifact: an absent version has one spelling (a literal null folds
230
+ // into undefined so identity comparisons and JSON round-trips can't split on it), `repo`, `vendored` and
231
+ // `subpackages` are validated, and `files` is null-prototype.
232
+ export function normalizeModule({ name, version, ecosystem, repo, vendored, subpackages, files }, dir, what) {
233
+ assert(ecosystem === undefined || typeof ecosystem === 'string')
234
+ files = fromEntries(Object.entries(files))
235
+ return moduleInfo({
236
+ name, version: version ?? undefined, ecosystem,
237
+ repo: normalizeModuleRepo(dir, { ecosystem, repo }, what),
238
+ vendored: normalizeDirMetadata('vendored', dir, { name, ecosystem, files, vendored }, what),
239
+ subpackages: normalizeDirMetadata('subpackages', dir, { name, ecosystem, files, subpackages }, what),
240
+ files,
241
+ })
242
+ }
243
+
244
+ // The keys a module map records -- the set an artifact's `executable` must be a subset of. `scope` MUST
245
+ // be the artifact's own: a non-full-scope artifact records only its node_modules buckets.
246
+ export function moduleFileKeys(modules, { scope = 'full' } = {}) {
247
+ const keys = new Set()
248
+ for (const [dir, { files }] of modules) {
249
+ if (scope !== 'full' && !hasNodeModulesSegment(dir)) continue
250
+ for (const rel of Object.keys(files)) keys.add(moduleFileKey(dir, rel))
251
+ }
252
+ return keys
253
+ }
254
+
255
+ // THE rule an artifact's `executable` entry must satisfy; returns the problem, or null when legal.
256
+ // parseExecutable (read), assertExecutable (write) and narrowExecutable share it so they cannot drift.
257
+ function executableEntryProblem(file, { what, files, formats, scope }) {
258
+ if (file.includes('\\')) return "holds a '\\'"
259
+ if (posixPathEscapes(file)) return 'escapes the root'
260
+ if (scope !== 'full' && !hasNodeModulesSegment(file)) {
261
+ return `is outside node_modules, which a '${scope}'-scope ${what} does not record`
262
+ }
263
+ if (!files.has(file)) return `names no file the ${what} records`
264
+ const format = formats.get(file)
265
+ if (format === 'directory') return 'is a directory capture, not a file'
266
+ if (isStatFormat(format)) return `is a payload-free '${format}' record, not a file`
267
+ return null
268
+ }
269
+
270
+ // Applied at every write site, so the in-memory artifact is honest before it is ever serialized.
271
+ export function narrowExecutable(executable, { modules, formats, scope }) {
272
+ const out = new Set()
273
+ if (executable.size === 0) return out
274
+ const files = moduleFileKeys(modules, { scope })
275
+ for (const file of executable) {
276
+ if (executableEntryProblem(file, { what: 'artifact', files, formats, scope }) === null) out.add(file)
277
+ }
278
+ return out
279
+ }
280
+
281
+ function assertExecutable(executable, { what, files, formats, scope }) {
282
+ for (const file of executable) {
283
+ const problem = executableEntryProblem(file, { what, files, formats, scope })
284
+ assert(problem === null, `${what}: executable entry '${file}' ${problem}`)
285
+ }
286
+ }
287
+
288
+ export function parseExecutable(list, { what, files, formats, scope = 'full' }) {
289
+ if (list === undefined) return new Set()
290
+ const at = `${what}: executable`
291
+ assert(Array.isArray(list), `${at} must be an array of file paths`)
292
+ const out = new Set()
293
+ for (const file of list) {
294
+ assert(typeof file === 'string' && file !== '', `${at} entry must be a non-empty string`)
295
+ // A dupe would silently collapse in out.add() and round-trip to different bytes.
296
+ assert(!out.has(file), `${at} entry '${file}' is listed twice`)
297
+ out.add(file)
298
+ }
299
+ assertExecutable(out, { what, files, formats, scope })
300
+ return out
301
+ }
302
+
303
+ // The one choke point every producer goes through, so a write site that forgot to narrow fails HERE, not
304
+ // on the next read. Omitted when empty: keeps every pre-`executable` artifact byte-identical when rewritten.
305
+ export function serializeExecutable(executable, { what, modules, formats, scope }) {
306
+ if (executable.size === 0) return undefined
307
+ assertExecutable(executable, { what, files: moduleFileKeys(modules, { scope }), formats, scope })
308
+ return fileSetToObject(executable)
309
+ }
310
+
311
+ export function assert(condition, msg) {
312
+ if (!condition) throw new Error(msg)
313
+ }
314
+
315
+ export function sortPaths(a, b) {
316
+ const [al, bl] = [a.split('/'), b.split('/')]
317
+ while (al.length > 0 && al[0] === bl[0]) {
318
+ al.shift()
319
+ bl.shift()
320
+ }
321
+ if (al.length === 0 && bl.length === 0) return 0
322
+
323
+ // First process each file in dir, then subdirs
324
+ if (al.length < 2) return bl.length < 2 && al > bl ? 1 : -1
325
+ if (bl.length < 2) return 1
326
+
327
+ if (al[0] === '*') return -1
328
+ if (bl[0] === '*') return 1
329
+
330
+ if (al[0] === 'node_modules') return 1
331
+ if (bl[0] === 'node_modules') return -1
332
+
333
+ // Prefer example/ over example-something/
334
+ const [an, bn] = [al, bl].map((list) => list.join(String.fromCodePoint(0)))
335
+ if (an < bn) return -1
336
+ if (an > bn) return 1
337
+ throw new Error('Unreachable')
338
+ }
339
+
340
+ const byPath = (a, b) => sortPaths(a[0], b[0])
341
+
342
+ export const isPlainObject = (x) => x && [null, Object.prototype].includes(Object.getPrototypeOf(x))
343
+
344
+ export const fromEntries = (entries) => Object.setPrototypeOf(Object.fromEntries(entries), null)
345
+
346
+ export const fileSetToObject = (set) => [...set].toSorted(sortPaths)
347
+
348
+ // `sorted: false` only for a machine-only payload whose reader does not care about ordering (shard.js).
349
+ export const fileMapToObject = (map, { sorted = true } = {}) => {
350
+ const entries = sorted ? [...map].toSorted(byPath) : [...map]
351
+ return fromEntries(entries.map(([k, v]) => [k, v instanceof Map ? fileMapToObject(v, { sorted }) : v]))
352
+ }
353
+
354
+ // The Map at `map.get(key)`, created on first use.
355
+ export const nestedMap = (map, key) => map.get(key) ?? map.set(key, new Map()).get(key)
356
+
357
+ export const objectToMaps = (obj) => new Map(
358
+ Object.entries(obj).map(([k, v]) => [k, isPlainObject(v) ? objectToMaps(v) : v])
359
+ )
360
+
361
+ // True for an absolute path or any `..` hop that pops above the root, INCLUDING a mid-path one
362
+ // (`a/../../x`) that plain `startsWith('..')` would miss. A segment walk (not posix.normalize, whose
363
+ // verdict it matches -- see posix-path-escapes.test.js) so this module stays free of node:path:
364
+ // `.` and empty segments are skipped exactly as normalize collapses them, a real segment pushes, and
365
+ // a `..` with nothing left to pop is an escape -- normalize would keep it as a leading `..` forever.
366
+ export function posixPathEscapes(path) {
367
+ if (path.startsWith('/')) return true
368
+ // The walk can only return true via a literal '..' segment, so the ordinary keys skip the split.
369
+ if (!path.includes('..')) return false
370
+ let depth = 0
371
+ for (const segment of path.split('/')) {
372
+ if (segment === '.' || segment === '') continue
373
+ if (segment !== '..') depth++
374
+ else if (--depth < 0) return true
375
+ }
376
+ return false
377
+ }
378
+
379
+ // THE rule every path an artifact records must satisfy (a file key's too, see canonicalFileKey): in
380
+ // the root, and free of `\` -- part of a name off Windows, which stasis refuses everywhere rather than
381
+ // take for another path, and on Windows a separator a `..\x` would climb out by.
382
+ export const isRefusedPath = (path) => path.includes('\\') || posixPathEscapes(path)
383
+
384
+ // Throws unless `path`, one of `what`'s, is a path an artifact may record (see isRefusedPath).
385
+ export const assertArtifactPath = (path, what) =>
386
+ assert(!isRefusedPath(path), `${what}: path '${path}' escapes the root or holds a '\\'`)
387
+
388
+ // THE rule an artifact's entry must satisfy, on read (parseEntries) and on write (serializeEntries).
389
+ const assertEntry = (entry, what) =>
390
+ assert(typeof entry === 'string' && entry !== '' && !isRefusedPath(entry), `${what}: invalid entry ${JSON.stringify(entry)}`)
391
+
392
+ // An artifact's `entries` list as a Set: each a non-empty in-root path, listed once (a dupe would
393
+ // collapse in the Set and round-trip to different bytes).
394
+ export function parseEntries(list, what) {
395
+ assert(Array.isArray(list), `${what}: entries must be an array of file paths`)
396
+ const out = new Set()
397
+ for (const entry of list) {
398
+ assertEntry(entry, what)
399
+ assert(!out.has(entry), `${what}: entry '${entry}' is listed twice`)
400
+ out.add(entry)
401
+ }
402
+ return out
403
+ }
404
+
405
+ // The `entries` list an artifact writes: the same rule as on read, so an in-memory construct can't
406
+ // serialize what parse would reject; path-sorted.
407
+ export function serializeEntries(entries, what) {
408
+ for (const entry of entries) assertEntry(entry, what)
409
+ return fileSetToObject(entries)
410
+ }
411
+
412
+ // THE rule an artifact's `formats` entry must satisfy, on read (parseFormats) and on write
413
+ // (serializeFormats): a path an artifact may record, and a known format.
414
+ function assertFormat(file, format) {
415
+ assertArtifactPath(file, 'formats')
416
+ assert(KNOWN_FORMATS.has(format), `unknown format '${format}' for ${file}`)
417
+ }
418
+
419
+ // An artifact's `formats` object as a validated Map. '' and '.' alias to the same key (older
420
+ // artifacts keyed the root listing ''); normalized, failing closed on dupes, and an unknown format
421
+ // is rejected at the schema boundary so a tampered artifact fails closed.
422
+ export function parseFormats(json) {
423
+ assert(isPlainObject(json))
424
+ const formats = new Map()
425
+ for (const [file, format] of Object.entries(json)) {
426
+ assertFormat(file, format)
427
+ const key = file === '' ? '.' : file
428
+ assert(!formats.has(key), `duplicate format key '${key}'`)
429
+ formats.set(key, format)
430
+ }
431
+ return formats
432
+ }
433
+
434
+ // The `formats` an artifact writes: the same rule as on read, so an in-memory construct can't serialize
435
+ // what parse would reject; path-sorted.
436
+ export function serializeFormats(formats) {
437
+ for (const [file, format] of formats) assertFormat(file, format)
438
+ return fileMapToObject(formats)
439
+ }
440
+
441
+ // THE rules an artifact's `imports` (conditions -> parent -> specifier -> target, as nested Maps)
442
+ // must satisfy, on read (parseImports) and on write (serializeImports). Paths escaping the root (incl.
443
+ // mid-path `a/../../x`) or holding a `\` are rejected: getImport resolves against the root at load. A
444
+ // target is a file, or (--metro) a non-empty { platform: file } map.
445
+ function assertImports(imports) {
446
+ for (const [, byParent] of imports) {
447
+ assert(byParent instanceof Map)
448
+ for (const [parent, specifiers] of byParent) {
449
+ assertArtifactPath(parent, 'imports')
450
+ assert(specifiers instanceof Map)
451
+ for (const [, target] of specifiers) {
452
+ if (typeof target === 'string') {
453
+ assertArtifactPath(target, 'imports')
454
+ continue
455
+ }
456
+ assert(target instanceof Map && target.size > 0, 'import target must be a file or a non-empty {platform: file} map')
457
+ for (const [platform, file] of target) {
458
+ assert(typeof platform === 'string' && platform.length > 0 && !platform.includes('/'), `invalid platform key '${platform}'`)
459
+ assert(typeof file === 'string')
460
+ assertArtifactPath(file, 'imports')
461
+ }
462
+ }
463
+ }
464
+ }
465
+ }
466
+
467
+ // An artifact's `imports` object as nested Maps (see assertImports).
468
+ export function parseImports(json) {
469
+ assert(isPlainObject(json))
470
+ const imports = objectToMaps(json)
471
+ assertImports(imports)
472
+ return imports
473
+ }
474
+
475
+ // The `imports` an artifact writes: the same rules as on read (see assertImports); path-sorted.
476
+ export function serializeImports(imports) {
477
+ assertImports(imports)
478
+ return fileMapToObject(imports)
479
+ }
480
+
481
+ // A module map as the serialized `modules` (node_modules buckets) and `sources` (the rest) objects
482
+ // of a `what` artifact, buckets and files path-sorted so the bytes are canonical. Each record's
483
+ // `vendored` and `subpackages` keep the entries holding one of the files it carries. `metadata` names the
484
+ // metadata fields written (a lockfile carries `vendored` alone, so it can be audited on its own), or is
485
+ // `true` for every one and `false` for none, as the option once was.
486
+ export function groupModules(modules, { skipEmpty = false, metadata: written = true, what } = {}) {
487
+ const metadata = written === true ? ['repo', ...Object.keys(DIR_METADATA)] : written === false ? [] : written
488
+ const grouped = { modules: [], sources: [] }
489
+ for (const [dir, info] of modules) {
490
+ if (skipEmpty && Object.keys(info.files).length === 0) continue
491
+ const inNodeModules = hasNodeModulesSegment(dir)
492
+ if (inNodeModules) assert(info.name && info.version && info.files)
493
+ const files = fromEntries(Object.entries(info.files).toSorted(byPath))
494
+ grouped[inNodeModules ? 'modules' : 'sources'].push([dir, moduleInfo({
495
+ ...info,
496
+ repo: metadata.includes('repo') ? normalizeModuleRepo(dir, info, what) : undefined,
497
+ ...carriedDirMetadata(dir, info, files, what, metadata),
498
+ files,
499
+ })])
500
+ }
501
+ return { modules: fromEntries(grouped.modules.toSorted(byPath)), sources: fromEntries(grouped.sources.toSorted(byPath)) }
502
+ }
503
+
504
+ // A target is a resolved-file string, or a { platform: file } Map under --metro.
505
+ function importTargetsEqual(a, b) {
506
+ const aMap = a instanceof Map
507
+ if (aMap !== (b instanceof Map)) return false
508
+ if (!aMap) return a === b
509
+ if (a.size !== b.size) return false
510
+ for (const [platform, file] of a) if (b.get(platform) !== file) return false
511
+ return true
512
+ }
513
+
514
+ const fmtTarget = (t) => (t instanceof Map ? `{${[...t].map(([p, f]) => `${p}: ${f}`).join(', ')}}` : t)
515
+
516
+ // Merge two import maps (conditions -> parent -> specifier -> target); a redirect conflict throws.
517
+ export function mergeImportMaps(a, b, label) {
518
+ const out = new Map()
519
+ const absorb = (imports) => {
520
+ for (const [conditions, byParent] of imports) {
521
+ const outByParent = nestedMap(out, conditions)
522
+ for (const [parent, specs] of byParent) {
523
+ const outSpecs = nestedMap(outByParent, parent)
524
+ for (const [spec, target] of specs) {
525
+ if (outSpecs.has(spec)) {
526
+ assert(importTargetsEqual(outSpecs.get(spec), target),
527
+ `${label}: import '${spec}' from '${parent}' resolves differently ('${fmtTarget(outSpecs.get(spec))}' vs '${fmtTarget(target)}')`)
528
+ } else {
529
+ outSpecs.set(spec, target instanceof Map ? new Map(target) : target)
530
+ }
531
+ }
532
+ }
533
+ }
534
+ }
535
+ absorb(a)
536
+ absorb(b)
537
+ return out
538
+ }
539
+
540
+ export function mergeFormatMaps(a, b, label) {
541
+ const out = new Map()
542
+ const absorb = (formats) => {
543
+ for (const [file, format] of formats) {
544
+ const currentFormat = out.get(file)
545
+ if (currentFormat === undefined) {
546
+ out.set(file, format)
547
+ continue
548
+ }
549
+ try {
550
+ out.set(file, reconcileFormat(format, currentFormat, file))
551
+ } catch (cause) {
552
+ throw new Error(`${label}: ${cause.message}`, { cause })
553
+ }
554
+ }
555
+ }
556
+ absorb(a)
557
+ absorb(b)
558
+ return out
559
+ }
560
+
561
+ // A union, EXCEPT that `b` (the INCOMING, newer artifact -- every call site passes it on the right) is
562
+ // authoritative for its own files: a since-lost execute bit is cleared, not resurrected by the union.
563
+ export function mergeExecutableSets(a, b, bModules, scope) {
564
+ if (a.size === 0) return new Set(b)
565
+ const bFiles = moduleFileKeys(bModules, { scope })
566
+ const out = new Set(b)
567
+ for (const file of a) if (!bFiles.has(file)) out.add(file)
568
+ return out
569
+ }
570
+
571
+ // An empty, '.' or '..' path segment.
572
+ const NON_CANONICAL_SEGMENT = /(?:^|\/)\.{0,2}(?:\/|$)/u
573
+
574
+ // The flat key of `rel` in bucket `dir`; throws unless canonical ('.' only as the root listing, rel '')
575
+ // and free of `\`, which no artifact path holds: off Windows it is part of a name, refused everywhere.
576
+ export function canonicalFileKey(dir, rel, what) {
577
+ const key = moduleFileKey(dir, rel)
578
+ // Message built only on failure: this runs for every file.
579
+ if ((key !== '.' || rel !== '') && NON_CANONICAL_SEGMENT.test(key)) assert(false, `${what}: non-canonical file key ${JSON.stringify(key)}`)
580
+ if (key.includes('\\')) assert(false, `${what}: file key '${key}' holds a '\\', which no path may`)
581
+ return key
582
+ }
583
+
584
+ // Maps each file's flat key to its bucket; rejects non-canonical keys and refused bucket dirs (an empty
585
+ // bucket's too, which no file key would reach), reports duplicates to onDuplicate.
586
+ export function flatFileKeys(modules, what, onDuplicate) {
587
+ const owners = new Map()
588
+ for (const [dir, { files }] of modules) {
589
+ if (typeof dir !== 'string') assert(false, `${what}: bucket dir ${String(dir)} is not a string`)
590
+ assertArtifactPath(dir, what)
591
+ for (const rel of Object.keys(files)) {
592
+ const key = canonicalFileKey(dir, rel, what)
593
+ const owner = owners.get(key)
594
+ if (owner !== undefined) onDuplicate(key, owner, dir)
595
+ owners.set(key, dir)
596
+ }
597
+ }
598
+ return owners
599
+ }
600
+
601
+ // The flatFileKeys duplicate handler for an artifact's parse/serialize: two bucket splits flattening
602
+ // to one path means module bucketing changed between writes.
603
+ export const duplicateKeyError = (what, regenerate) => (key) => assert(false,
604
+ `duplicate file key '${key}' across ${what} buckets -- module bucketing changed between writes ` +
605
+ `(a workspace package without a version now owns its own bucket); regenerate the ${regenerate}`)
606
+
607
+ // Result `files` objects are null-prototype, so a `__proto__` file name is a plain own key.
608
+ export function mergeModuleMaps(a, b, label) {
609
+ const out = new Map()
610
+ const absorb = (modules) => {
611
+ for (const [dir, info] of modules) {
612
+ const existing = out.get(dir)
613
+ if (existing === undefined) {
614
+ out.set(dir, moduleInfo({ ...info, files: Object.assign(Object.create(null), info.files) }))
615
+ continue
616
+ }
617
+ assert(existing.name === info.name,
618
+ `${label}: module '${dir}' name mismatch ('${existing.name}' vs '${info.name}')`)
619
+ // A one-sided absent version is usually a migration skew: older stasis fabricated '0.0.0'
620
+ // for a workspace package whose package.json has no version, newer stasis records none.
621
+ assert(existing.version === info.version,
622
+ `${label}: module '${dir}' version mismatch ('${existing.version}' vs '${info.version}')` +
623
+ ((existing.version == null) === (info.version == null) ? '' :
624
+ ` -- an artifact from an older stasis may record a placeholder version for a workspace ` +
625
+ `package without one; regenerate it (bundle=replace / lock=replace)`))
626
+ assert(existing.ecosystem === info.ecosystem,
627
+ `${label}: module '${dir}' ecosystem mismatch ('${existing.ecosystem ?? '(none)'}' vs '${info.ecosystem ?? '(none)'}')`)
628
+ // `repo`, `vendored` and `subpackages` are metadata, held to nothing: either side's, where only one records it, else `a`'s.
629
+ const merged = withMetadataOf(existing, info)
630
+ if (merged !== existing) out.set(dir, merged)
631
+ for (const [rel, value] of Object.entries(info.files)) {
632
+ if (Object.hasOwn(existing.files, rel)) {
633
+ assert(existing.files[rel] === value, `${label}: content mismatch for '${moduleFileKey(dir, rel)}'`)
634
+ } else {
635
+ existing.files[rel] = value
636
+ }
637
+ }
638
+ }
639
+ }
640
+ absorb(a)
641
+ absorb(b)
642
+ // One project-relative path must live in exactly one bucket. Bucketing can change between
643
+ // releases (a versionless workspace package used to fall through to a parent bucket and now owns
644
+ // its own), and per-dir absorption cannot see that: without this check the merge would WRITE an
645
+ // artifact that then fails its own next parse on the duplicate-file-key guard.
646
+ flatFileKeys(out, label, (key, owner, dir) => assert(false,
647
+ `${label}: file '${key}' is bucketed under both '${owner}' and '${dir}' -- module bucketing ` +
648
+ `changed between the artifacts (a workspace package without a version now owns its own ` +
649
+ `bucket); regenerate the artifact (bundle=replace / lock=replace)`))
650
+ return out
651
+ }
652
+
653
+ // A full path SEGMENT, NOT a bare substring (`foo_node_modules/dep` is a source dir, not a bucket).
654
+ export function hasNodeModulesSegment(path) {
655
+ return path.split('/').includes('node_modules')
656
+ }
657
+
658
+ // Deepest segment-aligned `node_modules/` marker, or -1: `lastIndexOf` alone would also match a bare
659
+ // substring (`foo_node_modules/`), so a candidate only counts at the start or after a `/`.
660
+ function lastNodeModulesMarker(path) {
661
+ const marker = 'node_modules/'
662
+ let idx = path.length
663
+ while ((idx = path.lastIndexOf(marker, idx - 1)) !== -1) {
664
+ if (idx === 0 || path[idx - 1] === '/') return idx
665
+ }
666
+ return -1
667
+ }
668
+
669
+ export function splitNodeModulesPath(path) {
670
+ const marker = 'node_modules/'
671
+ const idx = lastNodeModulesMarker(path)
672
+ if (idx === -1) return null
673
+ const after = idx + marker.length
674
+ const parts = path.slice(after).split('/')
675
+ const pkgLen = parts[0].startsWith('@') ? 2 : 1
676
+ if (parts.length <= pkgLen || parts.slice(0, pkgLen).some((p) => !p)) return null
677
+ const name = parts.slice(0, pkgLen).join('/')
678
+ return { dir: path.slice(0, after) + name, rel: parts.slice(pkgLen).join('/'), name }
679
+ }