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

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,318 @@
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. Everything here is pure computation over caller-supplied values with no
4
+ // Node builtin imports at all, so the data-model entry points (`./bundle`, `./lockfile`) load in
5
+ // any JS runtime. Byte/name classification, fs observation and CLI parsing live in util.js, which
6
+ // re-exports this module so `@exodus/stasis-core/util` keeps serving the full set.
7
+
8
+ const sep = '/'
9
+
10
+ // KNOWN_FORMATS is the closed universe of `format` strings; parsers reject anything outside it.
11
+ export const NODE_FORMATS = new Set(['module', 'commonjs', 'json', 'module-typescript', 'commonjs-typescript'])
12
+ export const SOURCE_LANGUAGE_FORMATS = new Set(['solidity', 'php', 'shell', 'rust'])
13
+ export const NATIVE_BUILD_FORMATS = new Set([
14
+ 'java', 'kotlin', 'gradle', 'objc', 'objcpp', 'swift', 'c', 'cpp', 'c-header', 'cpp-header',
15
+ 'ruby', 'cmake', 'podspec', 'podfile', 'podfile-lock', 'template', 'xml', 'env', 'fastlane', 'pbxproj',
16
+ ])
17
+ export const RESOURCE_FORMATS = new Set(['resource', 'resource:base64'])
18
+ export const STAT_FORMATS = new Set(['stat:file', 'stat:directory'])
19
+ export const KNOWN_FORMATS = new Set([
20
+ ...NODE_FORMATS,
21
+ ...SOURCE_LANGUAGE_FORMATS,
22
+ ...NATIVE_BUILD_FORMATS,
23
+ ...RESOURCE_FORMATS,
24
+ 'patch', // a `.patch` unified diff (pnpm patchedDependencies, patch-package): UTF-8 text applied by a patch step
25
+ 'directory',
26
+ ...STAT_FORMATS,
27
+ ])
28
+
29
+ // Payload-free stat records: attest a path's KIND, no content, and yield to a real format.
30
+ export const isStatFormat = (format) => STAT_FORMATS.has(format)
31
+
32
+ // Gates reconcileFormat: a stat record only reconciles with a real format of the SAME kind.
33
+ const formatKind = (format) => (format === 'directory' || format === 'stat:directory' ? 'directory' : 'file')
34
+
35
+ // A weak 'stat:*' yields to a real format of the SAME kind and never displaces one; anything else throws.
36
+ export function reconcileFormat(format, currentFormat, name) {
37
+ if (format === currentFormat) return format
38
+ const stat = isStatFormat(format)
39
+ const currentStat = isStatFormat(currentFormat)
40
+ if (stat !== currentStat && formatKind(format) === formatKind(currentFormat)) {
41
+ return stat ? currentFormat : format
42
+ }
43
+ throw new Error(`format conflict for '${name}' ('${currentFormat}' vs '${format}')`)
44
+ }
45
+
46
+ // Flat project-relative key. `rel === ''` (a `directory` capture whose path IS a module root) keys the
47
+ // bare dir, never `${dir}/` -- a trailing slash breaks the round-trip.
48
+ export function moduleFileKey(dir, rel) {
49
+ if (rel === '') return dir
50
+ return dir === '.' ? rel : `${dir}/${rel}`
51
+ }
52
+
53
+ // The keys a module map records -- the set an artifact's `executable` must be a subset of. `scope` MUST
54
+ // be the artifact's own: a non-full-scope artifact records only its node_modules buckets.
55
+ export function moduleFileKeys(modules, { scope = 'full' } = {}) {
56
+ const keys = new Set()
57
+ for (const [dir, { files }] of modules) {
58
+ if (scope !== 'full' && !hasNodeModulesSegment(dir)) continue
59
+ for (const rel of Object.keys(files)) keys.add(moduleFileKey(dir, rel))
60
+ }
61
+ return keys
62
+ }
63
+
64
+ // THE rule an artifact's `executable` entry must satisfy; returns the problem, or null when legal.
65
+ // parseExecutable (read), assertExecutable (write) and narrowExecutable share it so they cannot drift.
66
+ function executableEntryProblem(file, { what, files, formats, scope }) {
67
+ if (posixPathEscapes(file)) return 'escapes the root'
68
+ if (scope !== 'full' && !hasNodeModulesSegment(file)) {
69
+ return `is outside node_modules, which a '${scope}'-scope ${what} does not record`
70
+ }
71
+ if (!files.has(file)) return `names no file the ${what} records`
72
+ const format = formats.get(file)
73
+ if (format === 'directory') return 'is a directory capture, not a file'
74
+ if (isStatFormat(format)) return `is a payload-free '${format}' record, not a file`
75
+ return null
76
+ }
77
+
78
+ // Applied at every write site, so the in-memory artifact is honest before it is ever serialized.
79
+ export function narrowExecutable(executable, { modules, formats, scope }) {
80
+ const out = new Set()
81
+ if (executable.size === 0) return out
82
+ const files = moduleFileKeys(modules, { scope })
83
+ for (const file of executable) {
84
+ if (executableEntryProblem(file, { what: 'artifact', files, formats, scope }) === null) out.add(file)
85
+ }
86
+ return out
87
+ }
88
+
89
+ function assertExecutable(executable, { what, files, formats, scope }) {
90
+ for (const file of executable) {
91
+ const problem = executableEntryProblem(file, { what, files, formats, scope })
92
+ assert(problem === null, `${what}: executable entry '${file}' ${problem}`)
93
+ }
94
+ }
95
+
96
+ export function parseExecutable(list, { what, files, formats, scope = 'full' }) {
97
+ if (list === undefined) return new Set()
98
+ const at = `${what}: executable`
99
+ assert(Array.isArray(list), `${at} must be an array of file paths`)
100
+ const out = new Set()
101
+ for (const file of list) {
102
+ assert(typeof file === 'string' && file !== '', `${at} entry must be a non-empty string`)
103
+ // A dupe would silently collapse in out.add() and round-trip to different bytes.
104
+ assert(!out.has(file), `${at} entry '${file}' is listed twice`)
105
+ out.add(file)
106
+ }
107
+ assertExecutable(out, { what, files, formats, scope })
108
+ return out
109
+ }
110
+
111
+ // The one choke point every producer goes through, so a write site that forgot to narrow fails HERE, not
112
+ // on the next read. Omitted when empty: keeps every pre-`executable` artifact byte-identical when rewritten.
113
+ export function serializeExecutable(executable, { what, modules, formats, scope }) {
114
+ if (executable.size === 0) return undefined
115
+ assertExecutable(executable, { what, files: moduleFileKeys(modules, { scope }), formats, scope })
116
+ return fileSetToObject(executable)
117
+ }
118
+
119
+ export function assert(condition, msg) {
120
+ if (!condition) throw new Error(msg)
121
+ }
122
+
123
+ export function sortPaths(a, b) {
124
+ const [al, bl] = [a.split(sep), b.split(sep)]
125
+ while (al.length > 0 && al[0] === bl[0]) {
126
+ al.shift()
127
+ bl.shift()
128
+ }
129
+ if (al.length === 0 && bl.length === 0) return 0
130
+
131
+ // First process each file in dir, then subdirs
132
+ if (al.length < 2) return bl.length < 2 && al > bl ? 1 : -1
133
+ if (bl.length < 2) return 1
134
+
135
+ if (al[0] === '*') return -1
136
+ if (bl[0] === '*') return 1
137
+
138
+ if (al[0] === 'node_modules') return 1
139
+ if (bl[0] === 'node_modules') return -1
140
+
141
+ // Prefer example/ over example-something/
142
+ const [an, bn] = [al, bl].map((list) => list.join(String.fromCodePoint(0)))
143
+ if (an < bn) return -1
144
+ if (an > bn) return 1
145
+ throw new Error('Unreachable')
146
+ }
147
+
148
+ export const isPlainObject = (x) => x && [null, Object.prototype].includes(Object.getPrototypeOf(x))
149
+
150
+ export const fromEntries = (entries) => Object.setPrototypeOf(Object.fromEntries(entries), null)
151
+
152
+ export const fileSetToObject = (set) => [...set].toSorted((a, b) => sortPaths(a, b))
153
+
154
+ // `sorted: false` only for a machine-only payload whose reader does not care about ordering (shard.js).
155
+ export const fileMapToObject = (map, { sorted = true } = {}) => {
156
+ if (!sorted) {
157
+ const out = Object.create(null)
158
+ for (const [k, v] of map) out[k] = v instanceof Map ? fileMapToObject(v, { sorted }) : v
159
+ return out
160
+ }
161
+ return fromEntries(
162
+ [...map]
163
+ .toSorted((a, b) => sortPaths(a[0], b[0]))
164
+ .map(([k, v]) => [k, v instanceof Map ? fileMapToObject(v, { sorted }) : v])
165
+ )
166
+ }
167
+
168
+ export const objectToMaps = (obj) => new Map(
169
+ Object.entries(obj).map(([k, v]) => [k, isPlainObject(v) ? objectToMaps(v) : v])
170
+ )
171
+
172
+ // True for an absolute path or any `..` hop that pops above the root, INCLUDING a mid-path one
173
+ // (`a/../../x`) that plain `startsWith('..')` would miss. A segment walk (not posix.normalize, whose
174
+ // verdict it matches -- see posix-path-escapes.test.js) so this module stays free of node:path:
175
+ // `.` and empty segments are skipped exactly as normalize collapses them, a real segment pushes, and
176
+ // a `..` with nothing left to pop is an escape -- normalize would keep it as a leading `..` forever.
177
+ export function posixPathEscapes(path) {
178
+ if (path.startsWith('/')) return true
179
+ let depth = 0
180
+ for (const segment of path.split('/')) {
181
+ if (segment === '.' || segment === '') continue
182
+ if (segment !== '..') depth++
183
+ else if (--depth < 0) return true
184
+ }
185
+ return false
186
+ }
187
+
188
+ // A target is a resolved-file string, or a { platform: file } Map under --metro.
189
+ function importTargetsEqual(a, b) {
190
+ const aMap = a instanceof Map
191
+ if (aMap !== (b instanceof Map)) return false
192
+ if (!aMap) return a === b
193
+ if (a.size !== b.size) return false
194
+ for (const [platform, file] of a) if (b.get(platform) !== file) return false
195
+ return true
196
+ }
197
+
198
+ const fmtTarget = (t) => (t instanceof Map ? `{${[...t].map(([p, f]) => `${p}: ${f}`).join(', ')}}` : t)
199
+
200
+ // Merge two import maps (conditions -> parent -> specifier -> target); a redirect conflict throws.
201
+ export function mergeImportMaps(a, b, label) {
202
+ const out = new Map()
203
+ const absorb = (imports) => {
204
+ for (const [conditions, byParent] of imports) {
205
+ let outByParent = out.get(conditions)
206
+ if (outByParent === undefined) out.set(conditions, (outByParent = new Map()))
207
+ for (const [parent, specs] of byParent) {
208
+ let outSpecs = outByParent.get(parent)
209
+ if (outSpecs === undefined) outByParent.set(parent, (outSpecs = new Map()))
210
+ for (const [spec, target] of specs) {
211
+ if (outSpecs.has(spec)) {
212
+ assert(importTargetsEqual(outSpecs.get(spec), target),
213
+ `${label}: import '${spec}' from '${parent}' resolves differently ('${fmtTarget(outSpecs.get(spec))}' vs '${fmtTarget(target)}')`)
214
+ } else {
215
+ outSpecs.set(spec, target instanceof Map ? new Map(target) : target)
216
+ }
217
+ }
218
+ }
219
+ }
220
+ }
221
+ absorb(a)
222
+ absorb(b)
223
+ return out
224
+ }
225
+
226
+ export function mergeFormatMaps(a, b, label) {
227
+ const out = new Map()
228
+ const absorb = (formats) => {
229
+ for (const [file, format] of formats) {
230
+ const currentFormat = out.get(file)
231
+ if (currentFormat === undefined) {
232
+ out.set(file, format)
233
+ continue
234
+ }
235
+ try {
236
+ out.set(file, reconcileFormat(format, currentFormat, file))
237
+ } catch (cause) {
238
+ throw new Error(`${label}: ${cause.message}`, { cause })
239
+ }
240
+ }
241
+ }
242
+ absorb(a)
243
+ absorb(b)
244
+ return out
245
+ }
246
+
247
+ // A union, EXCEPT that `b` (the INCOMING, newer artifact -- every call site passes it on the right) is
248
+ // authoritative for its own files: a since-lost execute bit is cleared, not resurrected by the union.
249
+ export function mergeExecutableSets(a, b, bModules, scope) {
250
+ if (a.size === 0) return new Set(b)
251
+ const bFiles = moduleFileKeys(bModules, { scope })
252
+ const out = new Set(b)
253
+ for (const file of a) if (!bFiles.has(file)) out.add(file)
254
+ return out
255
+ }
256
+
257
+ // Result `files` objects are null-prototype, so a `__proto__` file name is a plain own key.
258
+ export function mergeModuleMaps(a, b, label) {
259
+ const out = new Map()
260
+ const absorb = (modules) => {
261
+ for (const [dir, info] of modules) {
262
+ const existing = out.get(dir)
263
+ if (existing === undefined) {
264
+ out.set(dir, {
265
+ name: info.name,
266
+ version: info.version,
267
+ ...(info.ecosystem === undefined ? {} : { ecosystem: info.ecosystem }),
268
+ files: Object.assign(Object.create(null), info.files),
269
+ })
270
+ continue
271
+ }
272
+ assert(existing.name === info.name,
273
+ `${label}: module '${dir}' name mismatch ('${existing.name}' vs '${info.name}')`)
274
+ assert(existing.version === info.version,
275
+ `${label}: module '${dir}' version mismatch ('${existing.version}' vs '${info.version}')`)
276
+ assert(existing.ecosystem === info.ecosystem,
277
+ `${label}: module '${dir}' ecosystem mismatch ('${existing.ecosystem ?? '(none)'}' vs '${info.ecosystem ?? '(none)'}')`)
278
+ for (const [rel, value] of Object.entries(info.files)) {
279
+ if (Object.hasOwn(existing.files, rel)) {
280
+ assert(existing.files[rel] === value, `${label}: content mismatch for '${moduleFileKey(dir, rel)}'`)
281
+ } else {
282
+ existing.files[rel] = value
283
+ }
284
+ }
285
+ }
286
+ }
287
+ absorb(a)
288
+ absorb(b)
289
+ return out
290
+ }
291
+
292
+ // A full path SEGMENT, NOT a bare substring (`foo_node_modules/dep` is a source dir, not a bucket).
293
+ export function hasNodeModulesSegment(path) {
294
+ return path.split('/').includes('node_modules')
295
+ }
296
+
297
+ // Deepest segment-aligned `node_modules/` marker, or -1: `lastIndexOf` alone would also match a bare
298
+ // substring (`foo_node_modules/`), so a candidate only counts at the start or after a `/`.
299
+ function lastNodeModulesMarker(path) {
300
+ const marker = 'node_modules/'
301
+ let idx = path.length
302
+ while ((idx = path.lastIndexOf(marker, idx - 1)) !== -1) {
303
+ if (idx === 0 || path[idx - 1] === '/') return idx
304
+ }
305
+ return -1
306
+ }
307
+
308
+ export function splitNodeModulesPath(path) {
309
+ const marker = 'node_modules/'
310
+ const idx = lastNodeModulesMarker(path)
311
+ if (idx === -1) return null
312
+ const after = idx + marker.length
313
+ const parts = path.slice(after).split('/')
314
+ const pkgLen = parts[0].startsWith('@') ? 2 : 1
315
+ if (parts.length <= pkgLen || parts.slice(0, pkgLen).some((p) => !p)) return null
316
+ const name = parts.slice(0, pkgLen).join('/')
317
+ return { dir: path.slice(0, after) + name, rel: parts.slice(pkgLen).join('/'), name }
318
+ }
package/src/brotli.js CHANGED
@@ -2,16 +2,9 @@ import { constants as zlibConstants } from 'node:zlib'
2
2
 
3
3
  import { assert, isBrotliQuality, parseBrotliQuality } from './util.js'
4
4
 
5
- // Brotli's default quality is 11 (max) and the encoder is superlinear in input
6
- // size, so on a multi-MB source bundle it dominates write time. The quality is
7
- // tunable via `quality` (an integer 0..11, typically config.brotliQuality) or the
8
- // env var -- which must agree when both are set; the output is still a valid .br
9
- // at any quality. Production code pays the default cost for the best ratio.
10
- //
11
- // Kept out of `util.js` so that importing the generic helpers there (`sortPaths`,
12
- // `assertRealPathWithinBase`, …) doesn't transitively load `node:zlib`. Only the
13
- // code that actually compresses a bundle (`state.js`, `stasis bundle`) reaches
14
- // for this, and that code already imports zlib directly.
5
+ // Default brotli quality; 11 (max) costs far more for a marginal gain over 9.
6
+ export const DEFAULT_BROTLI_QUALITY = 9
7
+
15
8
  export function brotliOptions(quality) {
16
9
  if (quality !== undefined) {
17
10
  assert(isBrotliQuality(quality), `brotli quality must be an integer 0..11, got ${quality}`)
@@ -23,6 +16,5 @@ export function brotliOptions(quality) {
23
16
  `brotli quality ${quality} conflicts with EXODUS_STASIS_BROTLI_QUALITY=${raw}`)
24
17
  quality = n
25
18
  }
26
- if (quality === undefined) return undefined
27
- return { params: { [zlibConstants.BROTLI_PARAM_QUALITY]: quality } }
19
+ return { params: { [zlibConstants.BROTLI_PARAM_QUALITY]: quality ?? DEFAULT_BROTLI_QUALITY } }
28
20
  }
@@ -0,0 +1,66 @@
1
+ import { isUtf8 } from 'node:buffer'
2
+ import { existsSync, readFileSync } from 'node:fs'
3
+ import { dirname, isAbsolute, join, relative, resolve } from 'node:path'
4
+ import { findPackageJSON } from 'node:module'
5
+ import { pathToFileURL } from 'node:url'
6
+
7
+ import { assertRealPathWithinBase, toPosix } from './util.js'
8
+
9
+ export function packageType(file) {
10
+ const pkg = findPackageJSON(pathToFileURL(file).toString())
11
+ if (!pkg) return null
12
+ try {
13
+ const type = JSON.parse(readFileSync(pkg, 'utf8')).type
14
+ return type === 'module' || type === 'commonjs' ? type : null
15
+ } catch {
16
+ return null
17
+ }
18
+ }
19
+
20
+ // Nearest package.json (walking up) with both name and version; pkgDir is relative to baseDir ("." at the root). Null if none.
21
+ export function findPackageMetadata(baseDir, fileRelPath) {
22
+ let dir = dirname(fileRelPath)
23
+ while (true) {
24
+ const pkgPath = join(baseDir, dir, 'package.json')
25
+ if (existsSync(pkgPath)) {
26
+ try {
27
+ const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'))
28
+ if (pkg.name && pkg.version) return { pkgDir: dir, name: pkg.name, version: pkg.version }
29
+ } catch { /* malformed -- keep walking */ }
30
+ }
31
+ if (dir === '.' || dir === '/' || dir === '') return null
32
+ const parent = dirname(dir)
33
+ if (parent === dir) return null
34
+ dir = parent
35
+ }
36
+ }
37
+
38
+ export function normalizeEntries(entries, cwd) {
39
+ const baseDir = resolve(cwd)
40
+ return entries.map((e) => {
41
+ const abs = resolve(cwd, e)
42
+ const rel = toPosix(relative(baseDir, abs))
43
+ // On Windows path.relative() returns an absolute path across drives (no leading '..'), so reject that form too.
44
+ if (rel.startsWith('..') || isAbsolute(rel)) throw new Error(`Entry escapes baseDir: ${e}`)
45
+ return rel.replace(/^\.\//u, '')
46
+ })
47
+ }
48
+
49
+ // Bytes of a bundled module's `package.json`, or null to skip when it's absent on disk; non-UTF-8 aborts (never silently skipped).
50
+ export function readModuleManifest({ baseDir, realBase, rel } = {}) {
51
+ const absolute = join(baseDir, rel)
52
+ if (!existsSync(absolute)) return null
53
+ assertRealPathWithinBase(realBase, baseDir, rel)
54
+ const buf = readFileSync(absolute)
55
+ if (!isUtf8(buf)) throw new Error(`package.json is not valid UTF-8: ${rel}`)
56
+ return buf
57
+ }
58
+
59
+ // Never throws: a missing/unreadable/malformed file yields null.
60
+ export function readJson(file) {
61
+ try {
62
+ return JSON.parse(readFileSync(file, 'utf8'))
63
+ } catch {
64
+ return null
65
+ }
66
+ }