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

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/util.js CHANGED
@@ -1,32 +1,14 @@
1
1
  import { isUtf8 } from 'node:buffer'
2
- import * as fs from 'node:fs'
3
- import { basename, isAbsolute, join, posix, relative } from 'node:path'
2
+ import { basename, isAbsolute, join, relative, sep } from 'node:path'
4
3
  import { parseArgs } from 'node:util'
5
4
 
6
- // Snapshot before `stasis run --fs` patches fs: the patched realpathSync doesn't throw ENOENT (which
7
- // assertRealPathWithinBase relies on) and patched statSync answers with synthetic Stats modes.
8
- const { realpathSync, statSync } = fs
5
+ import { NODE_FORMATS } from './artifact-util.js'
6
+ import { diskHost } from './host.js'
9
7
 
10
- const sep = '/'
11
-
12
- // KNOWN_FORMATS is the closed universe of `format` strings; parsers reject anything outside it.
13
- export const NODE_FORMATS = new Set(['module', 'commonjs', 'json', 'module-typescript', 'commonjs-typescript'])
14
- export const SOURCE_LANGUAGE_FORMATS = new Set(['solidity', 'php', 'shell', 'rust'])
15
- export const NATIVE_BUILD_FORMATS = new Set([
16
- 'java', 'kotlin', 'gradle', 'objc', 'objcpp', 'swift', 'c', 'cpp', 'c-header', 'cpp-header',
17
- 'ruby', 'cmake', 'podspec', 'podfile', 'podfile-lock', 'template', 'xml', 'env', 'fastlane', 'pbxproj',
18
- ])
19
- export const RESOURCE_FORMATS = new Set(['resource', 'resource:base64'])
20
- export const STAT_FORMATS = new Set(['stat:file', 'stat:directory'])
21
- export const KNOWN_FORMATS = new Set([
22
- ...NODE_FORMATS,
23
- ...SOURCE_LANGUAGE_FORMATS,
24
- ...NATIVE_BUILD_FORMATS,
25
- ...RESOURCE_FORMATS,
26
- 'patch', // a `.patch` unified diff (pnpm patchedDependencies, patch-package): UTF-8 text applied by a patch step
27
- 'directory',
28
- ...STAT_FORMATS,
29
- ])
8
+ // The Node-side half of the util split: byte/name classification for the capture walks, fs/execute-bit
9
+ // observation and CLI parsing. The pure artifact data model lives in artifact-util.js, re-exported
10
+ // here so `@exodus/stasis-core/util` keeps serving the full set.
11
+ export * from './artifact-util.js'
30
12
 
31
13
  // JS_UNRESOLVED_EXTS (.js/.ts type/syntax-dependent, .jsx/.tsx transformed) classify as null, not a format.
32
14
  const NODE_EXT_FORMATS = new Map([
@@ -36,30 +18,25 @@ const NODE_EXT_FORMATS = new Map([
36
18
  const JS_UNRESOLVED_EXTS = new Set(['js', 'ts', 'jsx', 'tsx'])
37
19
  export const CODE_EXTENSIONS = new Set([...NODE_EXT_FORMATS.keys(), ...JS_UNRESOLVED_EXTS])
38
20
 
39
- // Payload-free stat records: attest a path's KIND, no content, and yield to a real format.
40
- export const isStatFormat = (format) => STAT_FORMATS.has(format)
41
-
42
- // Gates reconcileFormat: a stat record only reconciles with a real format of the SAME kind.
43
- const formatKind = (format) => (format === 'directory' || format === 'stat:directory' ? 'directory' : 'file')
44
-
45
- // A weak 'stat:*' yields to a real format of the SAME kind and never displaces one; anything else throws.
46
- export function reconcileFormat(format, currentFormat, name) {
47
- if (format === currentFormat) return format
48
- const stat = isStatFormat(format)
49
- const currentStat = isStatFormat(currentFormat)
50
- if (stat !== currentStat && formatKind(format) === formatKind(currentFormat)) {
51
- return stat ? currentFormat : format
52
- }
53
- throw new Error(`format conflict for '${name}' ('${currentFormat}' vs '${format}')`)
54
- }
55
-
56
21
  export function pathExt(filePath) {
57
22
  const m = /\.([^./\\]+)$/.exec(filePath)
58
23
  return m ? m[1].toLowerCase() : ''
59
24
  }
60
25
 
61
- // A native path as the '/'-joined form every artifact key uses (a no-op off Windows).
62
- export const toPosix = (path) => path.split(/[\\/]/u).join('/')
26
+ // A native path as the '/'-joined form every artifact key uses. Off Windows `\` is no separator but
27
+ // part of a name, and a name holding one is refused rather than taken for another path.
28
+ export function toPosix(path) {
29
+ if (sep === '\\') return path.replaceAll('\\', '/')
30
+ if (path.includes('\\')) throw new Error(`stasis: a path holding '\\' is not supported: ${path}`)
31
+ return path
32
+ }
33
+
34
+ // Whether a path.relative() result climbs out of its base: absolute, or beginning with a `..`
35
+ // SEGMENT -- a bare startsWith('..') would also reject a legitimate `..cache` name.
36
+ export const relativeEscapes = (rel) => rel === '..' || rel.startsWith('../') || rel.startsWith(`..${sep}`) || isAbsolute(rel)
37
+
38
+ // True when `path` is `base` or lies beneath it. Lexical: resolve real paths first where symlinks matter.
39
+ export const isPathWithin = (base, path) => !relativeEscapes(relative(base, path))
63
40
 
64
41
  // Both rules are needed: pathExt('.env.local') is 'local', and the extension rule alone misses `.env.*`.
65
42
  export function isDotEnvFile(name) {
@@ -165,8 +142,7 @@ const CODE_EXT_FORMATS = new Map([
165
142
  ['rs', 'rust'],
166
143
  ['patch', 'patch'],
167
144
  ['java', 'java'],
168
- ['kt', 'kotlin'],
169
- ['kts', 'kotlin'],
145
+ ['kt', 'kotlin'], ['kts', 'kotlin'],
170
146
  ['gradle', 'gradle'],
171
147
  ['m', 'objc'],
172
148
  ['mm', 'objcpp'],
@@ -179,15 +155,10 @@ const CODE_EXT_FORMATS = new Map([
179
155
  ['cmake', 'cmake'],
180
156
  ['podspec', 'podspec'],
181
157
  ['template', 'template'],
182
- ['xml', 'xml'],
183
- ['plist', 'xml'],
184
- ['xcprivacy', 'xml'],
185
- ['xcscheme', 'xml'],
186
- ['storyboard', 'xml'],
187
- ['entitlements', 'xml'],
158
+ ['xml', 'xml'], ['plist', 'xml'], ['xcprivacy', 'xml'], ['xcscheme', 'xml'],
159
+ ['storyboard', 'xml'], ['entitlements', 'xml'], ['xcworkspacedata', 'xml'],
188
160
  ['env', 'env'],
189
161
  ['pbxproj', 'pbxproj'],
190
- ['xcworkspacedata', 'xml'],
191
162
  ])
192
163
 
193
164
  // Code formats by exact (lowercased) basename, for names whose extension is too generic to key
@@ -223,11 +194,9 @@ const NATIVE_EXCLUDE_NAMES = new Set([
223
194
  'gradle-wrapper.properties', // the APP's wrapper drives the build, not a module's own
224
195
  ])
225
196
  export function isExcludedNativeFile(name, { win32 = process.platform === 'win32' } = {}) {
226
- const base = basename(name).toLowerCase()
227
- if (NATIVE_EXCLUDE_NAMES.has(base)) return true
197
+ if (NATIVE_EXCLUDE_NAMES.has(basename(name).toLowerCase())) return true
228
198
  const ext = pathExt(name)
229
- if (NATIVE_EXCLUDE_EXTS.has(ext)) return true
230
- return !win32 && ext === 'bat'
199
+ return NATIVE_EXCLUDE_EXTS.has(ext) || (!win32 && ext === 'bat')
231
200
  }
232
201
 
233
202
  export function isExcludedNativeDir(name, { win32 = process.platform === 'win32' } = {}) {
@@ -317,9 +286,8 @@ export function classifyFormat(name, { content } = {}) {
317
286
  // The Metro native capture's policy view. Returns { action, format }: 'code' (a native build input),
318
287
  // 'skip' (excluded noise, or a JS-family file matched BY EXTENSION -- Metro owns those), else 'resource'.
319
288
  export function classifyNativeCapture(name, { win32 = process.platform === 'win32', content } = {}) {
320
- if (isExcludedNativeFile(name, { win32 })) return { action: 'skip' }
321
289
  // `.env` files carry secrets: an automated capture must never sweep them in.
322
- if (isDotEnvFile(name)) return { action: 'skip' }
290
+ if (isExcludedNativeFile(name, { win32 }) || isDotEnvFile(name)) return { action: 'skip' }
323
291
  const base = basename(name).toLowerCase()
324
292
  // Name-matched code is always a native build input, even when its tag is a Node format the JS
325
293
  // graph would otherwise own.
@@ -328,8 +296,7 @@ export function classifyNativeCapture(name, { win32 = process.platform === 'win3
328
296
  if (byName !== undefined) return { action: 'code', format: byName }
329
297
  if (CODE_EXTENSIONS.has(pathExt(name))) return { action: 'skip' }
330
298
  const format = classifyFormat(name, { content })
331
- if (format !== undefined) return { action: 'code', format }
332
- return { action: 'resource' }
299
+ return format === undefined ? { action: 'resource' } : { action: 'code', format }
333
300
  }
334
301
 
335
302
  // The byte-level half of the native classification, refining what classifyNativeCapture derived from the
@@ -350,29 +317,7 @@ export function isNativeManifest(name) {
350
317
  // podspecs invoke them at pod-install). Project-relative, so react-native's `exports` can't hide them.
351
318
  export const RN_CORE_INCLUDE_FILES = ['sdks/hermes-engine/utils/replace_hermes_version.js']
352
319
 
353
- export function extSetsEqual(a, b) {
354
- if (a.size !== b.size) return false
355
- for (const ext of a) if (!b.has(ext)) return false
356
- return true
357
- }
358
-
359
- // Flat project-relative key. `rel === ''` (a `directory` capture whose path IS a module root) keys the
360
- // bare dir, never `${dir}/` -- a trailing slash breaks the round-trip.
361
- export function moduleFileKey(dir, rel) {
362
- if (rel === '') return dir
363
- return dir === '.' ? rel : `${dir}/${rel}`
364
- }
365
-
366
- // The keys a module map records -- the set an artifact's `executable` must be a subset of. `scope` MUST
367
- // be the artifact's own: a non-full-scope artifact records only its node_modules buckets.
368
- export function moduleFileKeys(modules, { scope = 'full' } = {}) {
369
- const keys = new Set()
370
- for (const [dir, { files }] of modules) {
371
- if (scope !== 'full' && !hasNodeModulesSegment(dir)) continue
372
- for (const rel of Object.keys(files)) keys.add(moduleFileKey(dir, rel))
373
- }
374
- return keys
375
- }
320
+ export const extSetsEqual = (a, b) => a.size === b.size && [...a].every((ext) => b.has(ext))
376
321
 
377
322
  export const EXECUTE_BITS = 0o111
378
323
 
@@ -380,279 +325,23 @@ export const isExecutableMode = (stats) => stats.isFile() && (stats.mode & EXECU
380
325
 
381
326
  // Tri-state: `undefined` means the mode could NOT be observed (gone mid-run, EACCES, ELOOP, a synthetic
382
327
  // bundle entry). Callers must not read that as "not executable" -- failing to look is not evidence.
383
- export function observeExecutable(abs) {
384
- let stats
385
- try {
386
- stats = statSync(abs, { throwIfNoEntry: false })
387
- } catch {
388
- return undefined
389
- }
390
- if (stats === undefined) return undefined
391
- return isExecutableMode(stats)
328
+ export function observeExecutable(abs, host = diskHost) {
329
+ const stats = host.stat(abs)
330
+ return stats === null ? undefined : isExecutableMode(stats)
392
331
  }
393
332
 
394
333
  // Boolean view for callers with nothing to refute (recording a fresh set from scratch).
395
- export const isExecutableFile = (abs) => observeExecutable(abs) === true
334
+ export const isExecutableFile = (abs, host) => observeExecutable(abs, host) === true
396
335
 
397
336
  // Windows reports no POSIX execute bits, so a capture there records none and must NOT read "no bit" as
398
337
  // "the bit was removed" and strip what a POSIX capture attested.
399
338
  export const canObserveExecuteBits = ({ win32 = process.platform === 'win32' } = {}) => !win32
400
339
 
401
- // THE rule an artifact's `executable` entry must satisfy; returns the problem, or null when legal.
402
- // parseExecutable (read), assertExecutable (write) and narrowExecutable share it so they cannot drift.
403
- function executableEntryProblem(file, { what, files, formats, scope }) {
404
- if (posixPathEscapes(file)) return 'escapes the root'
405
- if (scope !== 'full' && !hasNodeModulesSegment(file)) {
406
- return `is outside node_modules, which a '${scope}'-scope ${what} does not record`
407
- }
408
- if (!files.has(file)) return `names no file the ${what} records`
409
- const format = formats.get(file)
410
- if (format === 'directory') return 'is a directory capture, not a file'
411
- if (isStatFormat(format)) return `is a payload-free '${format}' record, not a file`
412
- return null
413
- }
414
-
415
- // Applied at every write site, so the in-memory artifact is honest before it is ever serialized.
416
- export function narrowExecutable(executable, { modules, formats, scope }) {
417
- const out = new Set()
418
- if (executable.size === 0) return out
419
- const files = moduleFileKeys(modules, { scope })
420
- for (const file of executable) {
421
- if (executableEntryProblem(file, { what: 'artifact', files, formats, scope }) === null) out.add(file)
422
- }
423
- return out
424
- }
425
-
426
- function assertExecutable(executable, { what, files, formats, scope }) {
427
- for (const file of executable) {
428
- const problem = executableEntryProblem(file, { what, files, formats, scope })
429
- assert(problem === null, `${what}: executable entry '${file}' ${problem}`)
430
- }
431
- }
432
-
433
- export function parseExecutable(list, { what, files, formats, scope = 'full' }) {
434
- if (list === undefined) return new Set()
435
- const at = `${what}: executable`
436
- assert(Array.isArray(list), `${at} must be an array of file paths`)
437
- const out = new Set()
438
- for (const file of list) {
439
- assert(typeof file === 'string' && file !== '', `${at} entry must be a non-empty string`)
440
- // A dupe would silently collapse in out.add() and round-trip to different bytes.
441
- assert(!out.has(file), `${at} entry '${file}' is listed twice`)
442
- out.add(file)
443
- }
444
- assertExecutable(out, { what, files, formats, scope })
445
- return out
446
- }
447
-
448
- // The one choke point every producer goes through, so a write site that forgot to narrow fails HERE, not
449
- // on the next read. Omitted when empty: keeps every pre-`executable` artifact byte-identical when rewritten.
450
- export function serializeExecutable(executable, { what, modules, formats, scope }) {
451
- if (executable.size === 0) return undefined
452
- assertExecutable(executable, { what, files: moduleFileKeys(modules, { scope }), formats, scope })
453
- return fileSetToObject(executable)
454
- }
455
-
456
340
  // Throws on a symlink escaping the bundle root: a crafted `link.sh -> /etc/passwd` must not pull an
457
- // external file into an attestable bundle. realpathSync surfaces ENOENT, which loaders treat as "missing".
458
- export function assertRealPathWithinBase(realBase, baseDir, relPath) {
459
- const real = realpathSync(join(baseDir, relPath))
460
- const rel = toPosix(relative(realBase, real))
461
- if (rel.startsWith('..') || isAbsolute(rel)) {
341
+ // external file into an attestable bundle. realpath surfaces ENOENT, which loaders treat as "missing".
342
+ export function assertRealPathWithinBase(realBase, baseDir, relPath, host = diskHost) {
343
+ const real = host.realpath(join(baseDir, relPath))
344
+ if (!isPathWithin(realBase, real)) {
462
345
  throw new Error(`Refusing to follow symlink escaping bundle root: ${relPath} -> ${real}`)
463
346
  }
464
347
  }
465
-
466
- export function assert(condition, msg) {
467
- if (!condition) throw new Error(msg)
468
- }
469
-
470
- export function sortPaths(a, b) {
471
- const [al, bl] = [a.split(sep), b.split(sep)]
472
- while (al.length > 0 && al[0] === bl[0]) {
473
- al.shift()
474
- bl.shift()
475
- }
476
- if (al.length === 0 && bl.length === 0) return 0
477
-
478
- // First process each file in dir, then subdirs
479
- if (al.length < 2) return bl.length < 2 && al > bl ? 1 : -1
480
- if (bl.length < 2) return 1
481
-
482
- if (al[0] === '*') return -1
483
- if (bl[0] === '*') return 1
484
-
485
- if (al[0] === 'node_modules') return 1
486
- if (bl[0] === 'node_modules') return -1
487
-
488
- // Prefer example/ over example-something/
489
- const [an, bn] = [al, bl].map((list) => list.join(String.fromCodePoint(0)))
490
- if (an < bn) return -1
491
- if (an > bn) return 1
492
- throw new Error('Unreachable')
493
- }
494
-
495
- export const isPlainObject = (x) => x && [null, Object.prototype].includes(Object.getPrototypeOf(x))
496
-
497
- export const fromEntries = (entries) => Object.setPrototypeOf(Object.fromEntries(entries), null)
498
-
499
- export const fileSetToObject = (set) => [...set].toSorted((a, b) => sortPaths(a, b))
500
-
501
- // `sorted: false` only for a machine-only payload whose reader does not care about ordering (shard.js).
502
- export const fileMapToObject = (map, { sorted = true } = {}) => {
503
- if (!sorted) {
504
- const out = Object.create(null)
505
- for (const [k, v] of map) out[k] = v instanceof Map ? fileMapToObject(v, { sorted }) : v
506
- return out
507
- }
508
- return fromEntries(
509
- [...map]
510
- .toSorted((a, b) => sortPaths(a[0], b[0]))
511
- .map(([k, v]) => [k, v instanceof Map ? fileMapToObject(v, { sorted }) : v])
512
- )
513
- }
514
-
515
- export const objectToMaps = (obj) => new Map(
516
- Object.entries(obj).map(([k, v]) => [k, isPlainObject(v) ? objectToMaps(v) : v])
517
- )
518
-
519
- // Normalizes first: plain `startsWith('..')` would miss a mid-path `..` that pops above the root.
520
- export function posixPathEscapes(path) {
521
- // Exact prefilter: normalize() can only yield a '..'-prefixed result from an input containing '..',
522
- // or an absolute one from an input already absolute.
523
- if (!path.includes('..') && !posix.isAbsolute(path)) return false
524
- const normalized = posix.normalize(path)
525
- return normalized === '..' || normalized.startsWith('../') || posix.isAbsolute(normalized)
526
- }
527
-
528
- // A target is a resolved-file string, or a { platform: file } Map under --metro.
529
- function importTargetsEqual(a, b) {
530
- const aMap = a instanceof Map
531
- if (aMap !== (b instanceof Map)) return false
532
- if (!aMap) return a === b
533
- if (a.size !== b.size) return false
534
- for (const [platform, file] of a) if (b.get(platform) !== file) return false
535
- return true
536
- }
537
-
538
- const fmtTarget = (t) => (t instanceof Map ? `{${[...t].map(([p, f]) => `${p}: ${f}`).join(', ')}}` : t)
539
-
540
- // Merge two import maps (conditions -> parent -> specifier -> target); a redirect conflict throws.
541
- export function mergeImportMaps(a, b, label) {
542
- const out = new Map()
543
- const absorb = (imports) => {
544
- for (const [conditions, byParent] of imports) {
545
- let outByParent = out.get(conditions)
546
- if (outByParent === undefined) out.set(conditions, (outByParent = new Map()))
547
- for (const [parent, specs] of byParent) {
548
- let outSpecs = outByParent.get(parent)
549
- if (outSpecs === undefined) outByParent.set(parent, (outSpecs = new Map()))
550
- for (const [spec, target] of specs) {
551
- if (outSpecs.has(spec)) {
552
- assert(importTargetsEqual(outSpecs.get(spec), target),
553
- `${label}: import '${spec}' from '${parent}' resolves differently ('${fmtTarget(outSpecs.get(spec))}' vs '${fmtTarget(target)}')`)
554
- } else {
555
- outSpecs.set(spec, target instanceof Map ? new Map(target) : target)
556
- }
557
- }
558
- }
559
- }
560
- }
561
- absorb(a)
562
- absorb(b)
563
- return out
564
- }
565
-
566
- export function mergeFormatMaps(a, b, label) {
567
- const out = new Map()
568
- const absorb = (formats) => {
569
- for (const [file, format] of formats) {
570
- const currentFormat = out.get(file)
571
- if (currentFormat === undefined) {
572
- out.set(file, format)
573
- continue
574
- }
575
- try {
576
- out.set(file, reconcileFormat(format, currentFormat, file))
577
- } catch (cause) {
578
- throw new Error(`${label}: ${cause.message}`, { cause })
579
- }
580
- }
581
- }
582
- absorb(a)
583
- absorb(b)
584
- return out
585
- }
586
-
587
- // A union, EXCEPT that `b` (the INCOMING, newer artifact -- every call site passes it on the right) is
588
- // authoritative for its own files: a since-lost execute bit is cleared, not resurrected by the union.
589
- export function mergeExecutableSets(a, b, bModules, scope) {
590
- if (a.size === 0) return new Set(b)
591
- const bFiles = moduleFileKeys(bModules, { scope })
592
- const out = new Set(b)
593
- for (const file of a) if (!bFiles.has(file)) out.add(file)
594
- return out
595
- }
596
-
597
- // Result `files` objects are null-prototype, so a `__proto__` file name is a plain own key.
598
- export function mergeModuleMaps(a, b, label) {
599
- const out = new Map()
600
- const absorb = (modules) => {
601
- for (const [dir, info] of modules) {
602
- const existing = out.get(dir)
603
- if (existing === undefined) {
604
- out.set(dir, {
605
- name: info.name,
606
- version: info.version,
607
- ...(info.ecosystem === undefined ? {} : { ecosystem: info.ecosystem }),
608
- files: Object.assign(Object.create(null), info.files),
609
- })
610
- continue
611
- }
612
- assert(existing.name === info.name,
613
- `${label}: module '${dir}' name mismatch ('${existing.name}' vs '${info.name}')`)
614
- assert(existing.version === info.version,
615
- `${label}: module '${dir}' version mismatch ('${existing.version}' vs '${info.version}')`)
616
- assert(existing.ecosystem === info.ecosystem,
617
- `${label}: module '${dir}' ecosystem mismatch ('${existing.ecosystem ?? '(none)'}' vs '${info.ecosystem ?? '(none)'}')`)
618
- for (const [rel, value] of Object.entries(info.files)) {
619
- if (Object.hasOwn(existing.files, rel)) {
620
- assert(existing.files[rel] === value, `${label}: content mismatch for '${moduleFileKey(dir, rel)}'`)
621
- } else {
622
- existing.files[rel] = value
623
- }
624
- }
625
- }
626
- }
627
- absorb(a)
628
- absorb(b)
629
- return out
630
- }
631
-
632
- // A full path SEGMENT, NOT a bare substring (`foo_node_modules/dep` is a source dir, not a bucket).
633
- export function hasNodeModulesSegment(path) {
634
- return path.split('/').includes('node_modules')
635
- }
636
-
637
- // Deepest segment-aligned `node_modules/` marker, or -1: `lastIndexOf` alone would also match a bare
638
- // substring (`foo_node_modules/`), so a candidate only counts at the start or after a `/`.
639
- function lastNodeModulesMarker(path) {
640
- const marker = 'node_modules/'
641
- let idx = path.length
642
- while ((idx = path.lastIndexOf(marker, idx - 1)) !== -1) {
643
- if (idx === 0 || path[idx - 1] === '/') return idx
644
- }
645
- return -1
646
- }
647
-
648
- export function splitNodeModulesPath(path) {
649
- const marker = 'node_modules/'
650
- const idx = lastNodeModulesMarker(path)
651
- if (idx === -1) return null
652
- const after = idx + marker.length
653
- const parts = path.slice(after).split('/')
654
- const pkgLen = parts[0].startsWith('@') ? 2 : 1
655
- if (parts.length <= pkgLen || parts.slice(0, pkgLen).some((p) => !p)) return null
656
- const name = parts.slice(0, pkgLen).join('/')
657
- return { dir: path.slice(0, after) + name, rel: parts.slice(pkgLen).join('/'), name }
658
- }