@exodus/stasis-core 1.0.0-beta.4 → 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.
@@ -20,7 +20,12 @@ assert(basename(jsname) === 'stasis-core' || pathsEqual(jsname, fileURLToPath(im
20
20
 
21
21
  function usage(prefix = '') {
22
22
  console.error(`${prefix}\nUsage:
23
- stasis-core run --lock=(add|replace|frozen|ignore) [--bundle=(add|replace|load|frozen|ignore)] [--bundle-file=path/to/bundle.br] [--resources-bundle-file=path/to/resources.br] [--dependencies] [--child-process] [--fs=(sync|async)] [--resources=ext,ext] [--brotli-quality=0..11] path/to/file.js ...
23
+ stasis-core run --lock=(add|replace|frozen|ignore) [--bundle=(add|replace|load|frozen|ignore)] [--bundle-file=path/to/bundle.br] [--resources-bundle-file=path/to/resources.br] [--dependencies] [--child-process] [--import=module ...] [--fs=(sync|async)] [--resources=ext,ext] [--brotli-quality=0..11] path/to/file.js ...
24
+ (--import forwards extra preload modules (repeatable) to the node process running the entry,
25
+ e.g. --import=./instrument.mjs for a setup/instrumentation preload; a preload's own module
26
+ graph is runner infrastructure like stasis's loader itself, so it stays out of the
27
+ lockfile/bundle -- except modules the app graph also reaches, which are attested like any
28
+ other app code)
24
29
  stasis-core add path/to/(file|dir) ...
25
30
  (adds the listed files to the project's bundle(s) with no dependency resolution;
26
31
  a directory expands to its files. Requires a stasis.config.json (all fields optional).)
@@ -51,12 +56,13 @@ if (command === '-v' || command === '--version') {
51
56
  debug: { type: 'boolean' },
52
57
  dependencies: { type: 'boolean' },
53
58
  'child-process': { type: 'boolean' },
59
+ import: { type: 'string', multiple: true },
54
60
  fs: { type: 'string' },
55
61
  resources: { type: 'string' },
56
62
  'brotli-quality': { type: 'string' },
57
63
  }
58
64
  const values = parseLeadingOptions(argv, options, {
59
- valueFlags: ['--bundle', '--bundle-file', '--resources-bundle-file', '--lock', '--resources', '--brotli-quality'],
65
+ valueFlags: ['--bundle', '--bundle-file', '--resources-bundle-file', '--lock', '--import', '--resources', '--brotli-quality'],
60
66
  onError: usage,
61
67
  })
62
68
  if (argv.length === 0) usage('Nothing to run: no path to file given')
@@ -85,7 +91,11 @@ if (command === '-v' || command === '--version') {
85
91
  }
86
92
  }
87
93
  const childProcess = values['child-process'] ? '1' : ''
88
- console.warn('[stasis-core] Running stasis with config:', { lock, scope, bundle, ...(bundleFile && { bundleFile }), ...(resourcesBundleFile && { resourcesBundleFile }), ...(childProcess && { childProcess: true }), ...(values.fs && { fs: values.fs }), ...(resources && { resources }), ...(brotliQuality !== undefined && { brotliQuality }) })
94
+ // --import: extra preload module(s) passed through to the spawned node. Node resolves each
95
+ // against the project cwd; they ride AFTER stasis's own loader import.
96
+ const imports = values.import ?? []
97
+ if (imports.some((s) => s === '')) usage('Error: --import requires a module specifier (e.g. --import=./instrument.mjs)')
98
+ console.warn('[stasis-core] Running stasis with config:', { lock, scope, bundle, ...(bundleFile && { bundleFile }), ...(resourcesBundleFile && { resourcesBundleFile }), ...(childProcess && { childProcess: true }), ...(imports.length > 0 && { import: imports }), ...(values.fs && { fs: values.fs }), ...(resources && { resources }), ...(brotliQuality !== undefined && { brotliQuality }) })
89
99
  if (debug) console.warn(`[stasis-core] Warning: stasis debug mode active`)
90
100
  setEnv('EXODUS_STASIS_LOCK', lock)
91
101
  setEnv('EXODUS_STASIS_SCOPE', scope)
@@ -99,6 +109,10 @@ if (command === '-v' || command === '--version') {
99
109
  // Only set when given: an unconditional setEnv('') would reject an ambient EXODUS_STASIS_BROTLI_QUALITY as a conflict.
100
110
  if (brotliQuality !== undefined) setEnv('EXODUS_STASIS_BROTLI_QUALITY', String(brotliQuality))
101
111
  const nodeArgs = ['--import', import.meta.resolve('../src/loader.js')]
112
+ // Passthrough preloads ride after the loader, so they evaluate under its hooks; their module
113
+ // graphs pass through uncaptured unless the app graph reaches them -- then they're promoted
114
+ // into the capture (see src/hooks.js).
115
+ for (const specifier of imports) nodeArgs.push('--import', specifier)
102
116
  const child = spawn(process.execPath, [...nodeArgs, ...argv], { stdio: 'inherit' })
103
117
  const [code, signal] = await once(child, 'close')
104
118
  // code is null when the child died from a signal; report 128+signo (shell convention) instead of the implicit 0
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@exodus/stasis-core",
3
- "version": "1.0.0-beta.4",
3
+ "version": "1.0.0-beta.5",
4
4
  "description": "Zero-dependency stasis runtime",
5
5
  "type": "module",
6
6
  "exports": {
@@ -12,6 +12,7 @@
12
12
  "./add": "./src/add.js",
13
13
  "./bundle-util": "./src/bundle-util.js",
14
14
  "./extract": "./src/extract.js",
15
+ "./host": "./src/host.js",
15
16
  "./lockfile": "./src/lockfile.js",
16
17
  "./util": "./src/util.js",
17
18
  "./brotli": "./src/brotli.js",
@@ -29,6 +30,7 @@
29
30
  "src/extract.js",
30
31
  "src/fs.js",
31
32
  "src/hooks.js",
33
+ "src/host.js",
32
34
  "src/loader.js",
33
35
  "src/lockfile.js",
34
36
  "src/package.cjs",
@@ -46,13 +48,13 @@
46
48
  },
47
49
  "repository": {
48
50
  "type": "git",
49
- "url": "git+https://github.com/ExodusOSS/stasis.git",
51
+ "url": "git+https://github.com/PreventiveMeasures/stasis.git",
50
52
  "directory": "stasis-core"
51
53
  },
52
54
  "author": "Exodus Movement, Inc.",
53
55
  "license": "MIT",
54
56
  "bugs": {
55
- "url": "https://github.com/ExodusOSS/stasis/issues"
57
+ "url": "https://github.com/PreventiveMeasures/stasis/issues"
56
58
  },
57
- "homepage": "https://github.com/ExodusOSS/stasis#readme"
59
+ "homepage": "https://github.com/PreventiveMeasures/stasis#readme"
58
60
  }
package/src/add.js CHANGED
@@ -6,24 +6,28 @@ import { brotliCompressSync, brotliDecompressSync } from 'node:zlib'
6
6
  import { Bundle } from './bundle.js'
7
7
  import { Lockfile } from './lockfile.js'
8
8
  import { brotliOptions } from './brotli.js'
9
- import { findPackageMetadata, normalizeEntries, packageType, readJson } from './bundle-util.js'
9
+ import { detectRepo, findPackageMetadata, normalizeEntries, packageType, readJson } from './bundle-util.js'
10
10
  import { canonicalizePath, sha512integrity } from './state-util.js'
11
- import { assertRealPathWithinBase, classifyFormat, hasNodeModulesSegment, isAutoExcludedDir, isAutoExcludedFile, isBinaryPlist, isBrotliQuality, isExecutableMode, moduleFileKey, parseResourcesOption, pathExt, sortPaths, splitNodeModulesPath, toPosix } from './util.js'
11
+ import { assertRealPathWithinBase, classifyFormat, hasNodeModulesSegment, isAutoExcludedDir, isAutoExcludedFile, isBinaryPlist, isBrotliQuality, isExecutableMode, moduleFileKey, moduleInfo, parseResourcesOption, pathExt, sortPaths, splitNodeModulesPath, toPosix } from './util.js'
12
12
 
13
13
  const CONFIG_FILE = 'stasis.config.json'
14
14
  const LOCK_FILE = 'stasis.lock.json'
15
15
 
16
- // LIMITATION: a `.js`/`.ts` with no package `type` falls back to commonjs -- use `.mjs`/`.cjs` or set `type` when the module system matters.
16
+ // A `.js`/`.ts` follows its package `type` (LIMITATION: none falls back to commonjs -- use `.mjs`/`.cjs`
17
+ // or set `type` when the module system matters). Any other name is classifyFormat's call: a format,
18
+ // null for a JS-family file (`.jsx`/`.tsx`: source attested with no loader format, as the runtime
19
+ // records one), undefined when unrecognized.
17
20
  function sourceFormat(absFile, content) {
18
21
  const ext = extname(absFile).toLowerCase()
19
22
  if (ext === '.js' || ext === '.ts') return `${packageType(absFile) ?? 'commonjs'}${ext === '.ts' ? '-typescript' : ''}`
20
- return classifyFormat(absFile, { content }) ?? null
23
+ return classifyFormat(absFile, { content })
21
24
  }
22
25
 
23
- const tally = (bundle) => {
26
+ // File and non-empty package counts of a bundle or lockfile.
27
+ const tally = (artifact) => {
24
28
  let files = 0
25
29
  let packages = 0
26
- for (const m of bundle.modules.values()) {
30
+ for (const m of artifact.modules.values()) {
27
31
  const n = Object.keys(m.files).length
28
32
  if (n > 0) {
29
33
  files += n
@@ -53,19 +57,15 @@ function readAddConfig(baseDir) {
53
57
  }
54
58
 
55
59
  // Assemble a Bundle bucketed per package.json. `add` records NO entries -- its files are attested, not entry points -- so nothing in an add bundle is runnable via `--bundle=load`.
56
- function assembleBundle(baseDir, files, workspaceName, workspaceVersion) {
60
+ function assembleBundle(baseDir, files, workspaceName, workspaceVersion, repo) {
57
61
  const modules = new Map()
58
62
  const formats = new Map()
59
63
  const executable = new Set()
60
- const ensureBucket = (dir, name, version, ecosystem) => {
61
- if (!modules.has(dir)) {
62
- modules.set(dir, ecosystem === undefined
63
- ? { name, version, files: Object.create(null) }
64
- : { name, version, ecosystem, files: Object.create(null) })
65
- }
66
- return modules.get(dir)
64
+ const bucketFiles = (dir, name, version, ecosystem) => {
65
+ if (!modules.has(dir)) modules.set(dir, moduleInfo({ name, version, ecosystem, files: Object.create(null) }))
66
+ return modules.get(dir).files
67
67
  }
68
- // Memoize per directory: findPackageMetadata's result depends only on the file's directory.
68
+ // findPackageMetadata's result depends only on the file's directory.
69
69
  const metaByDir = new Map()
70
70
  const metaFor = (rel) => {
71
71
  const dir = dirname(rel)
@@ -75,31 +75,21 @@ function assembleBundle(baseDir, files, workspaceName, workspaceVersion) {
75
75
 
76
76
  for (const [rel, { content, format, executable: isExec }] of files) {
77
77
  const meta = metaFor(rel)
78
- const inNodeModules = splitNodeModulesPath(rel) !== null
78
+ // A node_modules file whose nearest package.json is the workspace root (or none at all) is a misconfigured dep -- refuse.
79
+ if (splitNodeModulesPath(rel) !== null && !(meta && hasNodeModulesSegment(meta.pkgDir))) {
80
+ throw new Error(`add: no package.json with name+version found for ${rel}`)
81
+ }
79
82
  if (meta) {
80
- // A node_modules file whose nearest package.json is the workspace root is a misconfigured dep -- refuse.
81
- if (inNodeModules && !hasNodeModulesSegment(meta.pkgDir)) {
82
- throw new Error(`add: no package.json with name+version found for ${rel}`)
83
- }
84
83
  const relInBucket = meta.pkgDir === '.' ? rel : rel.slice(meta.pkgDir.length + 1)
85
- const ecosystem = hasNodeModulesSegment(meta.pkgDir) ? 'npm' : undefined
86
- ensureBucket(meta.pkgDir, meta.name, meta.version, ecosystem).files[relInBucket] = content
84
+ bucketFiles(meta.pkgDir, meta.name, meta.version, hasNodeModulesSegment(meta.pkgDir) ? 'npm' : undefined)[relInBucket] = content
87
85
  } else {
88
- if (inNodeModules) throw new Error(`add: no package.json with name+version found for ${rel}`)
89
- ensureBucket('.', workspaceName, workspaceVersion).files[rel] = content
86
+ bucketFiles('.', workspaceName, workspaceVersion)[rel] = content
90
87
  }
91
- formats.set(rel, format)
88
+ if (format != null) formats.set(rel, format)
92
89
  if (isExec) executable.add(rel)
93
90
  }
94
91
 
95
- return new Bundle({
96
- config: { scope: 'full' },
97
- entries: new Set(),
98
- modules,
99
- formats,
100
- imports: new Map(),
101
- executable,
102
- }).withReason('add')
92
+ return new Bundle({ config: { scope: 'full' }, entries: new Set(), modules, formats, imports: new Map(), executable, repo }).withReason('add')
103
93
  }
104
94
 
105
95
  // Merge add-if-missing into any existing bundle (divergent bytes for an attested path throw -- see
@@ -135,7 +125,7 @@ function bundleToLockfile(bundle, integrities) {
135
125
  for (const [dir, m] of bundle.modules) {
136
126
  const files = Object.create(null)
137
127
  for (const rel of Object.keys(m.files)) files[rel] = integrities.get(moduleFileKey(dir, rel))
138
- modules.set(dir, { name: m.name, version: m.version, ...(m.ecosystem === undefined ? {} : { ecosystem: m.ecosystem }), files })
128
+ modules.set(dir, moduleInfo({ ...m, files }))
139
129
  }
140
130
  return new Lockfile({ config: bundle.config, entries: bundle.entries, modules, imports: bundle.imports, formats: bundle.formats, executable: bundle.executable })
141
131
  }
@@ -168,12 +158,12 @@ function expandDirectories(baseDir, rels, outputs) {
168
158
  const files = new Map() // rel -> stats
169
159
  const excluded = new Set()
170
160
  for (const rel of rels) {
171
- const stats = statSync(join(baseDir, rel), { throwIfNoEntry: false })
161
+ const dirAbs = join(baseDir, rel)
162
+ const stats = statSync(dirAbs, { throwIfNoEntry: false })
172
163
  if (stats === undefined || !stats.isDirectory()) {
173
164
  files.set(rel, stats)
174
165
  continue
175
166
  }
176
- const dirAbs = join(baseDir, rel)
177
167
  const found = []
178
168
  for (const match of globSync('**/*', { cwd: dirAbs })) {
179
169
  const fileAbs = join(dirAbs, match)
@@ -181,8 +171,8 @@ function expandDirectories(baseDir, rels, outputs) {
181
171
  const fileStats = statSync(fileAbs, { throwIfNoEntry: false })
182
172
  if (fileStats?.isFile()) found.push([toPosix(relative(baseDir, fileAbs)), match, fileStats])
183
173
  }
184
- // Sorted because serialize() emits `reason` in insertion order (everything else it re-sorts):
185
- // without this, the attested bundle's BYTES would depend on readdir order.
174
+ // Sorted so the sweep is deterministic regardless of readdir order: artifact bytes are
175
+ // canonicalized by serialize() either way, but multi-file diagnostics keep a stable order.
186
176
  for (const [file, match, fileStats] of found.toSorted(([a], [b]) => sortPaths(a, b))) {
187
177
  if (toPosix(match).split('/').slice(0, -1).some(isAutoExcludedDir)
188
178
  || outputs.has(file) || isAutoExcludedFile(file)) excluded.add(file)
@@ -199,9 +189,9 @@ const listPaths = (rels) => [...rels].toSorted(sortPaths).join(', ')
199
189
  // One error for every file validation rejected, so a directory sweep names all of them at once
200
190
  // instead of one per re-run. A lone offender keeps its exact standalone message.
201
191
  function validationError({ missing, undeclared, nonUtf8 }) {
202
- // `one`/`many` per category; empty categories contribute nothing.
203
192
  const phrase = (items, one, many) => (items.length === 1 ? [one(items[0])] : items.length > 1 ? [many(items)] : [])
204
- const named = ({ rel, format }) => `${rel} (format '${format}')`
193
+ const withFormat = (format) => (format == null ? '' : ` (format '${format}')`)
194
+ const named = ({ rel, format }) => `${rel}${withFormat(format)}`
205
195
  const parts = [
206
196
  ...phrase(missing,
207
197
  (rel) => `file not found: ${rel}`,
@@ -210,7 +200,7 @@ function validationError({ missing, undeclared, nonUtf8 }) {
210
200
  (rel) => `${rel} is neither a recognized source file nor a declared resource; add its extension to "resources" in ${CONFIG_FILE}`,
211
201
  (rels) => `${rels.length} files are neither recognized source files nor declared resources; add their extensions to "resources" in ${CONFIG_FILE}: ${listPaths(rels)}`),
212
202
  ...phrase(nonUtf8,
213
- ({ rel, format }) => `${rel} is not valid UTF-8 (format '${format}')`,
203
+ ({ rel, format }) => `${rel} is not valid UTF-8${withFormat(format)}`,
214
204
  (bad) => `${bad.length} files are not valid UTF-8: ${bad.map(named).join(', ')}`),
215
205
  ]
216
206
  return new Error(`add: ${parts.join('; ')}`)
@@ -234,14 +224,13 @@ function validateFiles({ baseDir, realBase, files, resources, withIntegrity }) {
234
224
  continue
235
225
  }
236
226
  const executable = isExecutableMode(stats)
237
- // Refuse a symlink whose realpath escapes the project root -- a bundle carries only in-tree bytes.
238
227
  assertRealPathWithinBase(realBase, baseDir, rel)
239
228
  const abs = join(baseDir, rel)
240
229
  const buf = readFileSync(abs)
241
230
  if (withIntegrity) integrities.set(rel, sha512integrity(buf))
242
231
  const format = sourceFormat(abs, buf)
243
232
  // A binary plist can't be stored as the UTF-8 string its 'xml' format implies, so it is NOT source: it falls through to the resource branch (opaque base64).
244
- if (format !== null && !isBinaryPlist(rel, buf)) {
233
+ if (format !== undefined && !isBinaryPlist(rel, buf)) {
245
234
  // Source is stored as a UTF-8 string, so non-UTF-8 bytes would lossily diverge from the file on disk.
246
235
  if (isUtf8(buf)) codeFiles.set(rel, { content: buf.toString('utf8'), format, executable })
247
236
  else nonUtf8.push({ rel, format })
@@ -295,9 +284,10 @@ export function addCommand({ cwd = process.cwd(), entries, logLabel = 'stasis-co
295
284
  // ADD step: every target's merge is computed first, then the writes run -- see prepareBundleFile.
296
285
  const summary = []
297
286
  const writes = []
287
+ const repo = detectRepo(baseDir)
298
288
  const planTarget = (target, entriesForTarget, kind) => {
299
289
  if (entriesForTarget.size === 0) return
300
- const { write, counts } = prepareBundleFile(baseDir, target, assembleBundle(baseDir, entriesForTarget, workspaceName, workspaceVersion), brotliQuality)
290
+ const { write, counts } = prepareBundleFile(baseDir, target, assembleBundle(baseDir, entriesForTarget, workspaceName, workspaceVersion, repo), brotliQuality)
301
291
  writes.push(write)
302
292
  summary.push(`+${counts.added} ${kind} (${counts.total} total) -> ${counts.path}`)
303
293
  }
@@ -305,9 +295,8 @@ export function addCommand({ cwd = process.cwd(), entries, logLabel = 'stasis-co
305
295
  planTarget(bundleFile, codeFiles, 'source')
306
296
  planTarget(resourcesBundleFile, resourceFiles, 'resource')
307
297
  } else {
308
- const all = new Map([...codeFiles, ...resourceFiles])
309
298
  const kind = codeFiles.size > 0 && resourceFiles.size > 0 ? 'file' : resourceFiles.size > 0 ? 'resource' : 'source'
310
- planTarget(bundleFile, all, kind)
299
+ planTarget(bundleFile, new Map([...codeFiles, ...resourceFiles]), kind)
311
300
  }
312
301
 
313
302
  // One lockfile attests both split targets, so merge in every packed file's integrity (code + resources together).
@@ -1,11 +1,7 @@
1
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 = '/'
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.
9
5
 
10
6
  // KNOWN_FORMATS is the closed universe of `format` strings; parsers reject anything outside it.
11
7
  export const NODE_FORMATS = new Set(['module', 'commonjs', 'json', 'module-typescript', 'commonjs-typescript'])
@@ -29,15 +25,19 @@ export const KNOWN_FORMATS = new Set([
29
25
  // Payload-free stat records: attest a path's KIND, no content, and yield to a real format.
30
26
  export const isStatFormat = (format) => STAT_FORMATS.has(format)
31
27
 
32
- // Gates reconcileFormat: a stat record only reconciles with a real format of the SAME kind.
28
+ // The post-erasure family of a '-typescript' loader format ('module-typescript' -> 'module'): a
29
+ // transforming preload (`stasis run --import tsx`) resolves/serves a TypeScript file as the JS
30
+ // family it transpiles to, while the attestation keeps the on-disk format. undefined otherwise.
31
+ export const erasedTypeScriptFormat = (format) =>
32
+ format === 'module-typescript' ? 'module' : format === 'commonjs-typescript' ? 'commonjs' : undefined
33
+
33
34
  const formatKind = (format) => (format === 'directory' || format === 'stat:directory' ? 'directory' : 'file')
34
35
 
35
36
  // A weak 'stat:*' yields to a real format of the SAME kind and never displaces one; anything else throws.
36
37
  export function reconcileFormat(format, currentFormat, name) {
37
38
  if (format === currentFormat) return format
38
39
  const stat = isStatFormat(format)
39
- const currentStat = isStatFormat(currentFormat)
40
- if (stat !== currentStat && formatKind(format) === formatKind(currentFormat)) {
40
+ if (stat !== isStatFormat(currentFormat) && formatKind(format) === formatKind(currentFormat)) {
41
41
  return stat ? currentFormat : format
42
42
  }
43
43
  throw new Error(`format conflict for '${name}' ('${currentFormat}' vs '${format}')`)
@@ -50,6 +50,17 @@ export function moduleFileKey(dir, rel) {
50
50
  return dir === '.' ? rel : `${dir}/${rel}`
51
51
  }
52
52
 
53
+ // A module bucket record in canonical key order; `ecosystem` is omitted (not undefined) when absent.
54
+ export const moduleInfo = ({ name, version, ecosystem, files }) =>
55
+ ({ name, version, ...(ecosystem === undefined ? {} : { ecosystem }), files })
56
+
57
+ // A parsed bucket: an absent version has one spelling (a literal null folds into undefined so
58
+ // identity comparisons and JSON round-trips can't split on it), and `files` is null-prototype.
59
+ export function normalizeModule({ name, version, ecosystem, files }) {
60
+ assert(ecosystem === undefined || typeof ecosystem === 'string')
61
+ return moduleInfo({ name, version: version ?? undefined, ecosystem, files: fromEntries(Object.entries(files)) })
62
+ }
63
+
53
64
  // The keys a module map records -- the set an artifact's `executable` must be a subset of. `scope` MUST
54
65
  // be the artifact's own: a non-full-scope artifact records only its node_modules buckets.
55
66
  export function moduleFileKeys(modules, { scope = 'full' } = {}) {
@@ -64,6 +75,7 @@ export function moduleFileKeys(modules, { scope = 'full' } = {}) {
64
75
  // THE rule an artifact's `executable` entry must satisfy; returns the problem, or null when legal.
65
76
  // parseExecutable (read), assertExecutable (write) and narrowExecutable share it so they cannot drift.
66
77
  function executableEntryProblem(file, { what, files, formats, scope }) {
78
+ if (file.includes('\\')) return "holds a '\\'"
67
79
  if (posixPathEscapes(file)) return 'escapes the root'
68
80
  if (scope !== 'full' && !hasNodeModulesSegment(file)) {
69
81
  return `is outside node_modules, which a '${scope}'-scope ${what} does not record`
@@ -121,7 +133,7 @@ export function assert(condition, msg) {
121
133
  }
122
134
 
123
135
  export function sortPaths(a, b) {
124
- const [al, bl] = [a.split(sep), b.split(sep)]
136
+ const [al, bl] = [a.split('/'), b.split('/')]
125
137
  while (al.length > 0 && al[0] === bl[0]) {
126
138
  al.shift()
127
139
  bl.shift()
@@ -145,26 +157,23 @@ export function sortPaths(a, b) {
145
157
  throw new Error('Unreachable')
146
158
  }
147
159
 
160
+ const byPath = (a, b) => sortPaths(a[0], b[0])
161
+
148
162
  export const isPlainObject = (x) => x && [null, Object.prototype].includes(Object.getPrototypeOf(x))
149
163
 
150
164
  export const fromEntries = (entries) => Object.setPrototypeOf(Object.fromEntries(entries), null)
151
165
 
152
- export const fileSetToObject = (set) => [...set].toSorted((a, b) => sortPaths(a, b))
166
+ export const fileSetToObject = (set) => [...set].toSorted(sortPaths)
153
167
 
154
168
  // `sorted: false` only for a machine-only payload whose reader does not care about ordering (shard.js).
155
169
  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
- )
170
+ const entries = sorted ? [...map].toSorted(byPath) : [...map]
171
+ return fromEntries(entries.map(([k, v]) => [k, v instanceof Map ? fileMapToObject(v, { sorted }) : v]))
166
172
  }
167
173
 
174
+ // The Map at `map.get(key)`, created on first use.
175
+ export const nestedMap = (map, key) => map.get(key) ?? map.set(key, new Map()).get(key)
176
+
168
177
  export const objectToMaps = (obj) => new Map(
169
178
  Object.entries(obj).map(([k, v]) => [k, isPlainObject(v) ? objectToMaps(v) : v])
170
179
  )
@@ -176,6 +185,8 @@ export const objectToMaps = (obj) => new Map(
176
185
  // a `..` with nothing left to pop is an escape -- normalize would keep it as a leading `..` forever.
177
186
  export function posixPathEscapes(path) {
178
187
  if (path.startsWith('/')) return true
188
+ // The walk can only return true via a literal '..' segment, so the ordinary keys skip the split.
189
+ if (!path.includes('..')) return false
179
190
  let depth = 0
180
191
  for (const segment of path.split('/')) {
181
192
  if (segment === '.' || segment === '') continue
@@ -185,6 +196,122 @@ export function posixPathEscapes(path) {
185
196
  return false
186
197
  }
187
198
 
199
+ // THE rule every path an artifact records must satisfy (a file key's too, see canonicalFileKey): in
200
+ // the root, and free of `\` -- part of a name off Windows, which stasis refuses everywhere rather than
201
+ // take for another path, and on Windows a separator a `..\x` would climb out by.
202
+ export const isRefusedPath = (path) => path.includes('\\') || posixPathEscapes(path)
203
+
204
+ // Throws unless `path`, one of `what`'s, is a path an artifact may record (see isRefusedPath).
205
+ export const assertArtifactPath = (path, what) =>
206
+ assert(!isRefusedPath(path), `${what}: path '${path}' escapes the root or holds a '\\'`)
207
+
208
+ // THE rule an artifact's entry must satisfy, on read (parseEntries) and on write (serializeEntries).
209
+ const assertEntry = (entry, what) =>
210
+ assert(typeof entry === 'string' && entry !== '' && !isRefusedPath(entry), `${what}: invalid entry ${JSON.stringify(entry)}`)
211
+
212
+ // An artifact's `entries` list as a Set: each a non-empty in-root path, listed once (a dupe would
213
+ // collapse in the Set and round-trip to different bytes).
214
+ export function parseEntries(list, what) {
215
+ assert(Array.isArray(list), `${what}: entries must be an array of file paths`)
216
+ const out = new Set()
217
+ for (const entry of list) {
218
+ assertEntry(entry, what)
219
+ assert(!out.has(entry), `${what}: entry '${entry}' is listed twice`)
220
+ out.add(entry)
221
+ }
222
+ return out
223
+ }
224
+
225
+ // The `entries` list an artifact writes: the same rule as on read, so an in-memory construct can't
226
+ // serialize what parse would reject; path-sorted.
227
+ export function serializeEntries(entries, what) {
228
+ for (const entry of entries) assertEntry(entry, what)
229
+ return fileSetToObject(entries)
230
+ }
231
+
232
+ // THE rule an artifact's `formats` entry must satisfy, on read (parseFormats) and on write
233
+ // (serializeFormats): a path an artifact may record, and a known format.
234
+ function assertFormat(file, format) {
235
+ assertArtifactPath(file, 'formats')
236
+ assert(KNOWN_FORMATS.has(format), `unknown format '${format}' for ${file}`)
237
+ }
238
+
239
+ // An artifact's `formats` object as a validated Map. '' and '.' alias to the same key (older
240
+ // artifacts keyed the root listing ''); normalized, failing closed on dupes, and an unknown format
241
+ // is rejected at the schema boundary so a tampered artifact fails closed.
242
+ export function parseFormats(json) {
243
+ assert(isPlainObject(json))
244
+ const formats = new Map()
245
+ for (const [file, format] of Object.entries(json)) {
246
+ assertFormat(file, format)
247
+ const key = file === '' ? '.' : file
248
+ assert(!formats.has(key), `duplicate format key '${key}'`)
249
+ formats.set(key, format)
250
+ }
251
+ return formats
252
+ }
253
+
254
+ // The `formats` an artifact writes: the same rule as on read, so an in-memory construct can't serialize
255
+ // what parse would reject; path-sorted.
256
+ export function serializeFormats(formats) {
257
+ for (const [file, format] of formats) assertFormat(file, format)
258
+ return fileMapToObject(formats)
259
+ }
260
+
261
+ // THE rules an artifact's `imports` (conditions -> parent -> specifier -> target, as nested Maps)
262
+ // must satisfy, on read (parseImports) and on write (serializeImports). Paths escaping the root (incl.
263
+ // mid-path `a/../../x`) or holding a `\` are rejected: getImport resolves against the root at load. A
264
+ // target is a file, or (--metro) a non-empty { platform: file } map.
265
+ function assertImports(imports) {
266
+ for (const [, byParent] of imports) {
267
+ assert(byParent instanceof Map)
268
+ for (const [parent, specifiers] of byParent) {
269
+ assertArtifactPath(parent, 'imports')
270
+ assert(specifiers instanceof Map)
271
+ for (const [, target] of specifiers) {
272
+ if (typeof target === 'string') {
273
+ assertArtifactPath(target, 'imports')
274
+ continue
275
+ }
276
+ assert(target instanceof Map && target.size > 0, 'import target must be a file or a non-empty {platform: file} map')
277
+ for (const [platform, file] of target) {
278
+ assert(typeof platform === 'string' && platform.length > 0 && !platform.includes('/'), `invalid platform key '${platform}'`)
279
+ assert(typeof file === 'string')
280
+ assertArtifactPath(file, 'imports')
281
+ }
282
+ }
283
+ }
284
+ }
285
+ }
286
+
287
+ // An artifact's `imports` object as nested Maps (see assertImports).
288
+ export function parseImports(json) {
289
+ assert(isPlainObject(json))
290
+ const imports = objectToMaps(json)
291
+ assertImports(imports)
292
+ return imports
293
+ }
294
+
295
+ // The `imports` an artifact writes: the same rules as on read (see assertImports); path-sorted.
296
+ export function serializeImports(imports) {
297
+ assertImports(imports)
298
+ return fileMapToObject(imports)
299
+ }
300
+
301
+ // A module map as the serialized `modules` (node_modules buckets) and `sources` (the rest) objects,
302
+ // buckets and files path-sorted so the bytes are canonical.
303
+ export function groupModules(modules, { skipEmpty = false } = {}) {
304
+ const grouped = { modules: [], sources: [] }
305
+ for (const [dir, info] of modules) {
306
+ if (skipEmpty && Object.keys(info.files).length === 0) continue
307
+ const inNodeModules = hasNodeModulesSegment(dir)
308
+ if (inNodeModules) assert(info.name && info.version && info.files)
309
+ const files = fromEntries(Object.entries(info.files).toSorted(byPath))
310
+ grouped[inNodeModules ? 'modules' : 'sources'].push([dir, moduleInfo({ ...info, files })])
311
+ }
312
+ return { modules: fromEntries(grouped.modules.toSorted(byPath)), sources: fromEntries(grouped.sources.toSorted(byPath)) }
313
+ }
314
+
188
315
  // A target is a resolved-file string, or a { platform: file } Map under --metro.
189
316
  function importTargetsEqual(a, b) {
190
317
  const aMap = a instanceof Map
@@ -202,11 +329,9 @@ export function mergeImportMaps(a, b, label) {
202
329
  const out = new Map()
203
330
  const absorb = (imports) => {
204
331
  for (const [conditions, byParent] of imports) {
205
- let outByParent = out.get(conditions)
206
- if (outByParent === undefined) out.set(conditions, (outByParent = new Map()))
332
+ const outByParent = nestedMap(out, conditions)
207
333
  for (const [parent, specs] of byParent) {
208
- let outSpecs = outByParent.get(parent)
209
- if (outSpecs === undefined) outByParent.set(parent, (outSpecs = new Map()))
334
+ const outSpecs = nestedMap(outByParent, parent)
210
335
  for (const [spec, target] of specs) {
211
336
  if (outSpecs.has(spec)) {
212
337
  assert(importTargetsEqual(outSpecs.get(spec), target),
@@ -254,6 +379,42 @@ export function mergeExecutableSets(a, b, bModules, scope) {
254
379
  return out
255
380
  }
256
381
 
382
+ // An empty, '.' or '..' path segment.
383
+ const NON_CANONICAL_SEGMENT = /(?:^|\/)\.{0,2}(?:\/|$)/u
384
+
385
+ // The flat key of `rel` in bucket `dir`; throws unless canonical ('.' only as the root listing, rel '')
386
+ // and free of `\`, which no artifact path holds: off Windows it is part of a name, refused everywhere.
387
+ export function canonicalFileKey(dir, rel, what) {
388
+ const key = moduleFileKey(dir, rel)
389
+ // Message built only on failure: this runs for every file.
390
+ if ((key !== '.' || rel !== '') && NON_CANONICAL_SEGMENT.test(key)) assert(false, `${what}: non-canonical file key ${JSON.stringify(key)}`)
391
+ if (key.includes('\\')) assert(false, `${what}: file key '${key}' holds a '\\', which no path may`)
392
+ return key
393
+ }
394
+
395
+ // Maps each file's flat key to its bucket; rejects non-canonical keys and refused bucket dirs (an empty
396
+ // bucket's too, which no file key would reach), reports duplicates to onDuplicate.
397
+ export function flatFileKeys(modules, what, onDuplicate) {
398
+ const owners = new Map()
399
+ for (const [dir, { files }] of modules) {
400
+ if (typeof dir !== 'string') assert(false, `${what}: bucket dir ${String(dir)} is not a string`)
401
+ assertArtifactPath(dir, what)
402
+ for (const rel of Object.keys(files)) {
403
+ const key = canonicalFileKey(dir, rel, what)
404
+ const owner = owners.get(key)
405
+ if (owner !== undefined) onDuplicate(key, owner, dir)
406
+ owners.set(key, dir)
407
+ }
408
+ }
409
+ return owners
410
+ }
411
+
412
+ // The flatFileKeys duplicate handler for an artifact's parse/serialize: two bucket splits flattening
413
+ // to one path means module bucketing changed between writes.
414
+ export const duplicateKeyError = (what, regenerate) => (key) => assert(false,
415
+ `duplicate file key '${key}' across ${what} buckets -- module bucketing changed between writes ` +
416
+ `(a workspace package without a version now owns its own bucket); regenerate the ${regenerate}`)
417
+
257
418
  // Result `files` objects are null-prototype, so a `__proto__` file name is a plain own key.
258
419
  export function mergeModuleMaps(a, b, label) {
259
420
  const out = new Map()
@@ -261,18 +422,18 @@ export function mergeModuleMaps(a, b, label) {
261
422
  for (const [dir, info] of modules) {
262
423
  const existing = out.get(dir)
263
424
  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
- })
425
+ out.set(dir, moduleInfo({ ...info, files: Object.assign(Object.create(null), info.files) }))
270
426
  continue
271
427
  }
272
428
  assert(existing.name === info.name,
273
429
  `${label}: module '${dir}' name mismatch ('${existing.name}' vs '${info.name}')`)
430
+ // A one-sided absent version is usually a migration skew: older stasis fabricated '0.0.0'
431
+ // for a workspace package whose package.json has no version, newer stasis records none.
274
432
  assert(existing.version === info.version,
275
- `${label}: module '${dir}' version mismatch ('${existing.version}' vs '${info.version}')`)
433
+ `${label}: module '${dir}' version mismatch ('${existing.version}' vs '${info.version}')` +
434
+ ((existing.version == null) === (info.version == null) ? '' :
435
+ ` -- an artifact from an older stasis may record a placeholder version for a workspace ` +
436
+ `package without one; regenerate it (bundle=replace / lock=replace)`))
276
437
  assert(existing.ecosystem === info.ecosystem,
277
438
  `${label}: module '${dir}' ecosystem mismatch ('${existing.ecosystem ?? '(none)'}' vs '${info.ecosystem ?? '(none)'}')`)
278
439
  for (const [rel, value] of Object.entries(info.files)) {
@@ -286,6 +447,14 @@ export function mergeModuleMaps(a, b, label) {
286
447
  }
287
448
  absorb(a)
288
449
  absorb(b)
450
+ // One project-relative path must live in exactly one bucket. Bucketing can change between
451
+ // releases (a versionless workspace package used to fall through to a parent bucket and now owns
452
+ // its own), and per-dir absorption cannot see that: without this check the merge would WRITE an
453
+ // artifact that then fails its own next parse on the duplicate-file-key guard.
454
+ flatFileKeys(out, label, (key, owner, dir) => assert(false,
455
+ `${label}: file '${key}' is bucketed under both '${owner}' and '${dir}' -- module bucketing ` +
456
+ `changed between the artifacts (a workspace package without a version now owns its own ` +
457
+ `bucket); regenerate the artifact (bundle=replace / lock=replace)`))
289
458
  return out
290
459
  }
291
460