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

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/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@exodus/stasis-core",
3
- "version": "1.0.0-beta.11",
3
+ "version": "1.0.0-beta.13",
4
4
  "description": "Zero-dependency stasis runtime",
5
5
  "type": "module",
6
6
  "exports": {
package/src/add.js CHANGED
@@ -1,6 +1,6 @@
1
1
  import { isUtf8 } from 'node:buffer'
2
- import { existsSync, globSync, mkdirSync, readFileSync, realpathSync, statSync, writeFileSync } from 'node:fs'
3
- import { basename, dirname, extname, join, relative, resolve } from 'node:path'
2
+ import * as fs from 'node:fs'
3
+ import { basename, dirname, extname, join, matchesGlob, posix, relative, resolve, sep } from 'node:path'
4
4
  import { brotliCompressSync, brotliDecompressSync } from 'node:zlib'
5
5
 
6
6
  import { Bundle } from './bundle.js'
@@ -10,6 +10,10 @@ import { detectRepo, findPackageMetadata, normalizeEntries, packageType, readJso
10
10
  import { canonicalizePath, sha512integrity } from './state-util.js'
11
11
  import { assertRealPathWithinBase, classifyFormat, hasNodeModulesSegment, isAutoExcludedDir, isAutoExcludedFile, isBinaryPlist, isBrotliQuality, isExecutableMode, moduleFileKey, moduleInfo, parseResourcesOption, pathExt, sortPaths, splitNodeModulesPath, toPosix, withMetadataOf } from './util.js'
12
12
 
13
+ // Snapshotted before `stasis run --fs` patches node:fs: State#includeExtra sweeps `extra` with these
14
+ // at write, which must read the real disk, not be captured as the program's reads.
15
+ const { existsSync, globSync, mkdirSync, readFileSync, realpathSync, statSync, writeFileSync } = fs
16
+
13
17
  const CONFIG_FILE = 'stasis.config.json'
14
18
  const LOCK_FILE = 'stasis.lock.json'
15
19
 
@@ -57,7 +61,9 @@ function readAddConfig(baseDir) {
57
61
  }
58
62
 
59
63
  // 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`.
60
- function assembleBundle(baseDir, files, workspaceName, workspaceVersion, repo) {
64
+ // `buckets` (dir -> module) are identities to take for a dir over the one found there: those of the
65
+ // bundle the files will merge into, which may name its buckets otherwise (`solidity-bundle`, say).
66
+ function assembleBundle(baseDir, files, workspaceName, workspaceVersion, repo, { reason = 'add', buckets = new Map() } = {}) {
61
67
  const modules = new Map()
62
68
  const formats = new Map()
63
69
  const executable = new Set()
@@ -65,6 +71,7 @@ function assembleBundle(baseDir, files, workspaceName, workspaceVersion, repo) {
65
71
  // file's adds the vendored package it is in.
66
72
  const bucketFiles = (dir, identity) => {
67
73
  const bucket = modules.get(dir)
74
+ identity = buckets.get(dir) ?? identity
68
75
  modules.set(dir, bucket === undefined ? moduleInfo({ ...identity, files: Object.create(null) }) : withMetadataOf(bucket, identity))
69
76
  return modules.get(dir).files
70
77
  }
@@ -92,7 +99,7 @@ function assembleBundle(baseDir, files, workspaceName, workspaceVersion, repo) {
92
99
  if (isExec) executable.add(rel)
93
100
  }
94
101
 
95
- return new Bundle({ config: { scope: 'full' }, entries: new Set(), modules, formats, imports: new Map(), executable, repo }).withReason('add')
102
+ return new Bundle({ config: { scope: 'full' }, entries: new Set(), modules, formats, imports: new Map(), executable, repo }).withReason(reason)
96
103
  }
97
104
 
98
105
  // Merge add-if-missing into any existing bundle (divergent bytes for an attested path throw -- see
@@ -148,27 +155,69 @@ function prepareLockfile(lockPath, lockAdd) {
148
155
  return { write: () => writeFileSync(lockPath, merged.serialize()), counts: { total, added: total - before } }
149
156
  }
150
157
 
158
+ // Whether a project-relative path, with its stats (undefined when missing), is one of `outputs`
159
+ // (project-relative): by name, or as the same file under another, a symlink or hard link to it -- its
160
+ // device and inode, which a write rewrites in place. Stats as numbers can round a large inode
161
+ // (Windows file ids), so a match on those is settled exactly (bigint), never taken on its own.
162
+ function outputMatcher(baseDir, outputs) {
163
+ const exact = new Set()
164
+ const rounded = new Set()
165
+ for (const rel of outputs) {
166
+ const stats = statSync(join(baseDir, rel), { throwIfNoEntry: false, bigint: true })
167
+ if (stats === undefined) continue
168
+ exact.add(`${stats.dev}:${stats.ino}`)
169
+ rounded.add(`${Number(stats.dev)}:${Number(stats.ino)}`)
170
+ }
171
+ return (rel, stats) => {
172
+ if (outputs.has(rel)) return true
173
+ if (stats === undefined || !rounded.has(`${stats.dev}:${stats.ino}`)) return false
174
+ const precise = statSync(join(baseDir, rel), { throwIfNoEntry: false, bigint: true })
175
+ return precise !== undefined && exact.has(`${precise.dev}:${precise.ino}`)
176
+ }
177
+ }
178
+
179
+ // fs.globSync's matches of `pattern` under `cwd`, as paths relative to it, taking none `exclude` takes
180
+ // (given the path relative to `baseDir`, '/'-joined) and walking into none it takes. fs.globSync hands
181
+ // its callback a bare name for a file, so the walk is over Dirents, which know their parent. A visited
182
+ // name is checked as spelled: one holding `\` is for the caller to refuse where it is kept, not here.
183
+ function globPaths(pattern, cwd, baseDir, exclude) {
184
+ if (exclude === undefined) return globSync(pattern, { cwd })
185
+ const pathOf = (dirent) => join(dirent.parentPath, dirent.name)
186
+ const projectPath = (dirent) => {
187
+ const rel = relative(baseDir, pathOf(dirent))
188
+ return sep === '\\' ? rel.replaceAll('\\', '/') : rel
189
+ }
190
+ return globSync(pattern, { cwd, withFileTypes: true, exclude: (entry) => exclude(projectPath(entry)) })
191
+ .map((dirent) => relative(cwd, pathOf(dirent)))
192
+ }
193
+
151
194
  // GLOB + FILTER: expand each directory entry into the files under it (recursive glob), dropping the
152
195
  // auto-excluded set from what a sweep FINDS -- dir rules on the segments BELOW the named root (`add
153
196
  // src/examples` sweeps the dir it was pointed at, `add src` skips one it merely found), file rules
154
- // by name plus the caller's `outputs` (this run's own write targets). A path the caller NAMED is
155
- // always kept (naming is the override; a missing one keeps stats undefined so validation reports
156
- // it), and inclusion is monotone: a nearer root's sweep can only ever see FEWER excluded segments,
197
+ // by name plus the caller's `outputs` (this run's own write targets, by name or alias: outputMatcher).
198
+ // A path the caller NAMED is always kept (naming is the override; a missing one keeps stats undefined
199
+ // so validation reports it) -- unless `keepNamedOutputs` is false, then one of `outputs` never is --
200
+ // and inclusion is monotone: a nearer root's sweep can only ever see FEWER excluded segments,
157
201
  // so a path any entry keeps stays kept -- `add src src/examples` includes the subtree it names in
158
202
  // either order. `stats` is the walk's own stat, reused by validation. Gotcha: `**/*` skips dotfiles
159
- // (.env, .git/...) -- name them explicitly.
160
- function expandDirectories(baseDir, rels, outputs) {
203
+ // (.env, .git/...) -- name them explicitly. A project-relative path `exclude` takes is dropped, named
204
+ // or swept, with everything under it: a named path below one too, and a directory it takes is never
205
+ // walked (globPaths).
206
+ function expandDirectories(baseDir, rels, outputs, { keepNamedOutputs = true, exclude } = {}) {
161
207
  const files = new Map() // rel -> stats
162
208
  const excluded = new Set()
209
+ const isOutput = outputMatcher(baseDir, outputs)
163
210
  for (const rel of rels) {
211
+ // A walk meets a directory before what's under it, so it checks each path alone; a named one, its directories too.
212
+ if (exclude !== undefined && rel.split('/').some((_, i, segments) => exclude(segments.slice(0, i + 1).join('/')))) continue
164
213
  const dirAbs = join(baseDir, rel)
165
214
  const stats = statSync(dirAbs, { throwIfNoEntry: false })
166
215
  if (stats === undefined || !stats.isDirectory()) {
167
- files.set(rel, stats)
216
+ if (keepNamedOutputs || !isOutput(rel, stats)) files.set(rel, stats)
168
217
  continue
169
218
  }
170
219
  const found = []
171
- for (const match of globSync('**/*', { cwd: dirAbs })) {
220
+ for (const match of globPaths('**/*', dirAbs, baseDir, exclude)) {
172
221
  const fileAbs = join(dirAbs, match)
173
222
  // A dangling symlink stats as undefined -- skipped, not a hard ENOENT out of the walk.
174
223
  const fileStats = statSync(fileAbs, { throwIfNoEntry: false })
@@ -178,7 +227,7 @@ function expandDirectories(baseDir, rels, outputs) {
178
227
  // canonicalized by serialize() either way, but multi-file diagnostics keep a stable order.
179
228
  for (const [file, match, fileStats] of found.toSorted(([a], [b]) => sortPaths(a, b))) {
180
229
  if (toPosix(match).split('/').slice(0, -1).some(isAutoExcludedDir)
181
- || outputs.has(file) || isAutoExcludedFile(file)) excluded.add(file)
230
+ || isOutput(file, fileStats) || isAutoExcludedFile(file)) excluded.add(file)
182
231
  else files.set(file, fileStats)
183
232
  }
184
233
  }
@@ -190,8 +239,8 @@ function expandDirectories(baseDir, rels, outputs) {
190
239
  const listPaths = (rels) => [...rels].toSorted(sortPaths).join(', ')
191
240
 
192
241
  // One error for every file validation rejected, so a directory sweep names all of them at once
193
- // instead of one per re-run. A lone offender keeps its exact standalone message.
194
- function validationError({ missing, undeclared, nonUtf8 }) {
242
+ // instead of one per re-run. A lone offender keeps its exact standalone message. `label` prefixes it.
243
+ export function validationError({ missing, undeclared, nonUtf8 }, label) {
195
244
  const phrase = (items, one, many) => (items.length === 1 ? [one(items[0])] : items.length > 1 ? [many(items)] : [])
196
245
  const withFormat = (format) => (format == null ? '' : ` (format '${format}')`)
197
246
  const named = ({ rel, format }) => `${rel}${withFormat(format)}`
@@ -206,15 +255,35 @@ function validationError({ missing, undeclared, nonUtf8 }) {
206
255
  ({ rel, format }) => `${rel} is not valid UTF-8${withFormat(format)}`,
207
256
  (bad) => `${bad.length} files are not valid UTF-8: ${bad.map(named).join(', ')}`),
208
257
  ]
209
- return new Error(`add: ${parts.join('; ')}`)
258
+ return new Error(`${label}: ${parts.join('; ')}`)
259
+ }
260
+
261
+ // stasis.config.json's `extra` patterns, expanded as a shell expands `stasis add`'s arguments: each
262
+ // by Node's glob (whose `*` skips dotfiles, as the shell's does), a pattern matching nothing standing
263
+ // for itself as it does without bash's nullglob (so a missing path is reported missing), then each
264
+ // path as `add` takes it (expandDirectories): a file named or matched is kept, a directory swept.
265
+ // One of `outputs`, the files this very run writes, is never kept, named, matched (`dist/*`) or
266
+ // under another name (outputMatcher). A `!` entry (`!ios/Pods`, `!**/xcuserdata`) is no path: it
267
+ // takes out every path its pattern matches, in any order of the entries, along with everything under
268
+ // one that is a directory, which is then never walked, whether by a pattern's expansion or a sweep:
269
+ // a pattern whose every match is excluded matches nothing. One matching nothing is no error.
270
+ export function expandExtra(baseDir, patterns, outputs) {
271
+ // Normalized as the paths they're matched against are: no `./`, no trailing `/`.
272
+ const exclusions = patterns.filter((pattern) => pattern.startsWith('!')).map((pattern) => posix.normalize(pattern.slice(1)).replace(/\/+$/u, ''))
273
+ const exclude = exclusions.length === 0 ? undefined : (rel) => exclusions.some((pattern) => matchesGlob(rel, pattern))
274
+ const entries = patterns.filter((pattern) => !pattern.startsWith('!')).flatMap((pattern) => {
275
+ const matches = globPaths(pattern, baseDir, baseDir, exclude)
276
+ return matches.length === 0 ? [pattern] : matches.toSorted(sortPaths)
277
+ })
278
+ return expandDirectories(baseDir, normalizeEntries(entries, baseDir), outputs, { keepNamedOutputs: false, exclude })
210
279
  }
211
280
 
212
281
  // VALIDATE step: classify the WHOLE set -- each file recognized source or a declared resource --
213
282
  // before a single target is touched, collecting every offender into one error. `files` is the glob
214
283
  // step's rel -> stats map (stats undefined = not on disk). Containment is the one rule NOT collected:
215
284
  // a symlink escaping the root is a security invariant, so it fails closed on the spot. Bytes are
216
- // hashed only when there's a lockfile to receive the integrities (`withIntegrity`).
217
- function validateFiles({ baseDir, realBase, files, resources, withIntegrity }) {
285
+ // hashed only when there's a lockfile to receive the integrities (`withIntegrity`). `label` prefixes the error.
286
+ function validateFiles({ baseDir, realBase, files, resources, withIntegrity, label = 'add' }) {
218
287
  const codeFiles = new Map()
219
288
  const resourceFiles = new Map()
220
289
  const integrities = new Map()
@@ -244,10 +313,27 @@ function validateFiles({ baseDir, realBase, files, resources, withIntegrity }) {
244
313
  undeclared.push(rel)
245
314
  }
246
315
  }
247
- if (missing.length + undeclared.length + nonUtf8.length > 0) throw validationError({ missing, undeclared, nonUtf8 })
316
+ if (missing.length + undeclared.length + nonUtf8.length > 0) throw validationError({ missing, undeclared, nonUtf8 }, label)
248
317
  return { codeFiles, resourceFiles, integrities }
249
318
  }
250
319
 
320
+ // The files stasis.config.json's `extra` names under `baseDir` (expandExtra), packed as `add` packs
321
+ // them, for `stasis bundle` to merge into `bundle`, one built there without a State (always full
322
+ // scope): those it doesn't carry already (its own record of a file stands), in its buckets where it
323
+ // has them. `outputs` are the project-relative paths the build writes, never swept in.
324
+ // -> { bundle, lockfile } of the `extra` consumer (null when there is nothing to add), and
325
+ // `carried`: the files named that `bundle` carries already, the `extra` consumer's too
326
+ export function extraArtifacts({ baseDir, patterns, resources, bundle, outputs = new Set() }) {
327
+ const named = expandExtra(baseDir, patterns, outputs).files
328
+ const carried = [...named.keys()].filter((rel) => bundle.sources.has(rel))
329
+ const files = new Map([...named].filter(([rel]) => !bundle.sources.has(rel)))
330
+ if (files.size === 0) return { bundle: null, lockfile: null, carried }
331
+ const { codeFiles, resourceFiles, integrities } = validateFiles({ baseDir, realBase: realpathSync(baseDir), files, resources, withIntegrity: true, label: 'extra' })
332
+ const rootPkg = readJson(join(baseDir, 'package.json')) ?? {}
333
+ const extra = assembleBundle(baseDir, new Map([...codeFiles, ...resourceFiles]), rootPkg.name ?? 'workspace', rootPkg.version ?? '0.0.0', undefined, { reason: 'extra', buckets: bundle.modules })
334
+ return { bundle: extra, lockfile: bundleToLockfile(extra, integrities), carried }
335
+ }
336
+
251
337
  // GLOB the listed paths, FILTERING the auto-excluded set out of what a sweep finds (see
252
338
  // expandDirectories) -> VALIDATE the whole surviving set -> only then ADD it to the target
253
339
  // bundle(s), add-if-missing. A stasis.lock.json is updated only when one already exists.
@@ -67,6 +67,19 @@ export function namedManifestOf(rel, read) {
67
67
  return undefined
68
68
  }
69
69
 
70
+ // The package.json nearest above a file `rel` of the package at `pkgDir` (both project-relative,
71
+ // POSIX), short of the package's own: a `{"type":"module"}` marker such as `esm/package.json`, or a
72
+ // subpackage's or vendored package's, which Node takes the file's `type` from and Metro's resolver
73
+ // (getPackageForModule) the file's fields. `exists(rel)` says whether one is there -> its rel, or
74
+ // undefined where the package's own is the nearest.
75
+ export function scopeManifestOf(rel, pkgDir, exists) {
76
+ if (pkgDir !== '.' && !rel.startsWith(`${pkgDir}/`)) return undefined
77
+ for (let dir = posix.dirname(rel); dir !== pkgDir && dir !== '.'; dir = posix.dirname(dir)) {
78
+ if (exists(`${dir}/package.json`)) return `${dir}/package.json`
79
+ }
80
+ return undefined
81
+ }
82
+
70
83
  // Nearest package.json (walking up) that identifies a bucket; pkgDir is relative to baseDir ("."
71
84
  // at the root). Inside node_modules both name and version are required; a workspace package
72
85
  // outside node_modules may omit version (the name alone claims the bucket, matching
@@ -341,7 +354,7 @@ function repositoryUrl(json) {
341
354
  // The `repo` a parsed package.json's `repository` names for `rel`, a directory below it ('' for its
342
355
  // own): `github` from its GitHub URL or shorthand, and `directory` from `repository.directory` joined
343
356
  // with `rel` (declaredLocation); undefined where it names no GitHub repository.
344
- export function packageRepo(json, rel = '') {
357
+ function declaredRepo(json, rel) {
345
358
  const github = parseGithubRepository(repositoryUrl(json))
346
359
  if (!github) return undefined
347
360
  let base = json.repository.directory
@@ -354,8 +367,18 @@ export function packageRepo(json, rel = '') {
354
367
  return { github, ...declaredLocation(base, rel) }
355
368
  }
356
369
 
370
+ // A dependency's `repo`, from its parsed package.json: the repository it names (declaredRepo), at the
371
+ // commit its `gitHead` names where that is a full one. npm publish writes `gitHead` into the
372
+ // registry's version document alone, but lerna writes it into the published package.json too, and
373
+ // npm keeps one a package.json has, so the two agree. Undefined where it names no GitHub repository.
374
+ export function packageRepo(json) {
375
+ const repo = declaredRepo(json, '')
376
+ return repo !== undefined && isValidRepoField('commit', json.gitHead) ? { ...repo, commit: json.gitHead } : repo
377
+ }
378
+
357
379
  // Bundle `repo` for `dir`: git origin/HEAD at the work tree root, with `dir`'s place in it (`''` at
358
- // the root), else nearest package.json `repository` (packageRepo).
380
+ // the root), else nearest package.json `repository` (declaredRepo). Its commit is git's HEAD alone,
381
+ // never a package.json's `gitHead`: a project's own files are likely changed since the one it names.
359
382
  export function detectRepo(dir, host = diskHost) {
360
383
  const start = resolve(dir)
361
384
  let pkg = null // null: no package.json `repository` seen yet; undefined: one seen, not GitHub
@@ -363,7 +386,7 @@ export function detectRepo(dir, host = diskHost) {
363
386
  const rel = toPosix(relative(cursor, start))
364
387
  if (pkg === null) {
365
388
  const json = readJson(join(cursor, 'package.json'), host)
366
- if (repositoryUrl(json) !== undefined) pkg = packageRepo(json, rel)
389
+ if (repositoryUrl(json) !== undefined) pkg = declaredRepo(json, rel)
367
390
  }
368
391
  const dotGit = join(cursor, '.git')
369
392
  if (host.stat(dotGit) !== null) {
package/src/bundle.js CHANGED
@@ -285,10 +285,10 @@ export class Bundle {
285
285
  return JSON.stringify(data, undefined, 2)
286
286
  }
287
287
 
288
- // Stamp `consumer` onto every carried file in the informational `reason` map.
289
- withReason(consumer) {
288
+ // Stamp `consumer` onto `files` in the informational `reason` map: by default every carried file.
289
+ withReason(consumer, files = [...this.sources.keys()]) {
290
290
  const { version, config, entries, modules, formats, imports, executable, repo, package: pkg } = this
291
- const reason = mergeReason(this.reason, { [consumer]: [...this.sources.keys()] })
291
+ const reason = mergeReason(this.reason, { [consumer]: files })
292
292
  return new Bundle({ version, config, entries, modules, formats, imports, executable, reason, repo, package: pkg })
293
293
  }
294
294
 
package/src/config.js CHANGED
@@ -2,7 +2,7 @@ import assert from 'node:assert/strict'
2
2
 
3
3
  import { diskHost } from './host.js'
4
4
  import { canonicalizePath } from './state-util.js'
5
- import { extSetsEqual, isBrotliQuality, parseBrotliQuality, parseResourcesOption } from './util.js'
5
+ import { extSetsEqual, isBrotliQuality, parseBrotliQuality, parseExtraOption, parseResourcesOption } from './util.js'
6
6
 
7
7
  export const DEFAULT_LOCK = 'add'
8
8
  export const DEFAULT_BUNDLE = 'none'
@@ -19,7 +19,10 @@ const envBool = (name, value) => {
19
19
  const envList = (value) => value.split(',').map((s) => s.trim()).filter(Boolean)
20
20
 
21
21
  // Every option: its env var, how the env string parses (strings pass through) and, for a non-string
22
- // option, how a `new Config()` option does. `lockFile` is flag/env-only (never from stasis.config.json).
22
+ // option, how a `new Config()` option does. `lockFile` and `bundle` are flag/env-only (never from
23
+ // stasis.config.json), and the file's `lock` can only be CONFIG_FILE_LOCK; `extra` is the reverse,
24
+ // stasis.config.json only (no env var or option), and `entries` is `stasis bundle`'s, which a run
25
+ // takes nothing from.
23
26
  const OPTIONS = {
24
27
  scope: { env: 'EXODUS_STASIS_SCOPE', valid: new Set(['node_modules', 'full']) },
25
28
  lock: { env: 'EXODUS_STASIS_LOCK', valid: new Set(['none', 'ignore', 'add', 'replace', 'frozen']) },
@@ -36,7 +39,10 @@ const OPTIONS = {
36
39
  resources: { env: 'EXODUS_STASIS_RESOURCES', parse: (name, value) => parseResourcesOption('env', envList(value)), option: (value) => parseResourcesOption('options', value) },
37
40
  }
38
41
  const OPTION_KEYS = Object.keys(OPTIONS)
39
- const CONFIG_FILE_KEYS = OPTION_KEYS.filter((key) => key !== 'lockFile')
42
+ const CONFIG_FILE_KEYS = [...OPTION_KEYS.filter((key) => key !== 'lockFile' && key !== 'bundle'), 'extra', 'entries']
43
+ // The one mode a stasis.config.json can pin: a run that writes, loads or ignores is given its modes
44
+ // explicitly (flags, env, options), never by a file.
45
+ const CONFIG_FILE_LOCK = 'frozen'
40
46
  const PLUGIN_OPTION_KEYS = ['scope', 'lock', 'bundle', 'bundleFile', 'resourcesBundleFile', 'debug', 'childProcess', 'packageJSON', 'resources']
41
47
 
42
48
  const assertKnownKeys = (keys, known, what) => {
@@ -125,6 +131,7 @@ export class Config {
125
131
  fs: str('fs', undefined),
126
132
  brotliQuality: this.#envValue('brotliQuality') ?? explicit.brotliQuality,
127
133
  resources: parseResourcesOption('resources', this.#env.resources !== undefined ? envList(this.#env.resources) : explicit.resources),
134
+ extra: [],
128
135
  }
129
136
  const flush = env.EXODUS_STASIS_SHARD_SIGNAL_FLUSH
130
137
  this.#shardSignalFlush = Boolean(flush) && envBool('EXODUS_STASIS_SHARD_SIGNAL_FLUSH', flush)
@@ -197,9 +204,18 @@ export class Config {
197
204
  loadConfig(json) {
198
205
  const config = JSON.parse(json)
199
206
  const keys = Object.keys(config)
207
+ if (keys.includes('bundle')) {
208
+ throw new Error('stasis.config.json: bundle can not be set here; give the bundle mode explicitly (--bundle, EXODUS_STASIS_BUNDLE)')
209
+ }
210
+ if (keys.includes('lock') && config.lock !== CONFIG_FILE_LOCK) {
211
+ throw new Error(`stasis.config.json: lock can only be '${CONFIG_FILE_LOCK}' (got ${JSON.stringify(config.lock)}); give any other lock mode explicitly (--lock, EXODUS_STASIS_LOCK)`)
212
+ }
200
213
  assert.equal(keys.filter((key) => !CONFIG_FILE_KEYS.includes(key)).length, 0)
201
214
  for (const key of keys) {
215
+ // `stasis bundle`'s, validated there.
216
+ if (key === 'entries') continue
202
217
  if (key === 'resources') this.#opts.resources = parseResourcesOption('stasis.config.json', config.resources)
218
+ else if (key === 'extra') this.#opts.extra = parseExtraOption('stasis.config.json', config.extra)
203
219
  // '' -> undefined like the constructor: otherwise canonicalizePath('') claims cwd as a write target.
204
220
  else if (key === 'bundleFile' || key === 'resourcesBundleFile') this.#opts[key] = config[key] || undefined
205
221
  else this.#opts[key] = config[key]
@@ -242,6 +258,11 @@ export class Config {
242
258
  return this.#opts.resources
243
259
  }
244
260
 
261
+ // stasis.config.json's `extra` patterns, attested beside what a writing run reaches (State#includeExtra). Not serialized.
262
+ get extra() {
263
+ return this.#opts.extra
264
+ }
265
+
245
266
  get debug() {
246
267
  return this.#opts.debug
247
268
  }
@@ -337,9 +358,11 @@ export class Config {
337
358
  return this.#opts.lock
338
359
  }
339
360
 
361
+ // As a stasis.config.json holds it: `lock` only where it is the one a file can pin, `bundle` never.
340
362
  get json() {
341
- const { scope, lock, bundle, resources } = this.#opts
342
- const data = { scope, lock, bundle }
363
+ const { scope, lock, resources } = this.#opts
364
+ const data = { scope }
365
+ if (lock === CONFIG_FILE_LOCK) data.lock = lock
343
366
  // Only serialize `resources` when non-empty, so configs without an allowlist stay byte-identical.
344
367
  if (resources.size > 0) data.resources = [...resources].toSorted()
345
368
  return JSON.stringify(data, undefined, 2) + '\n'
package/src/fs.js CHANGED
@@ -135,6 +135,10 @@ export function installFsHooks({ async: patchAsync, getState, markAborted, isLoa
135
135
  if (installed) return
136
136
  installed = true
137
137
 
138
+ // Node's glob takes fs's readers when it first loads: load it now, on the real ones, so the sweep
139
+ // of stasis.config.json's `extra` at write (expandExtra) is never captured as the program's reads.
140
+ fs.globSync([])
141
+
138
142
  // Classify a path for every hook: null passes through to the real fs; else { mode, abs, url, state }
139
143
  // with mode 'absent' (a skipped path: ENOENT), 'serve' (bundle=load; an uncaptured path still falls
140
144
  // through to disk) or 'capture' (bundle=add|replace, outside a loader read).
package/src/hooks.js CHANGED
@@ -32,6 +32,9 @@ function refuseNonNodeFormat(format, url) {
32
32
  if (format === 'directory') {
33
33
  throw new Error(`[stasis] cannot import a directory listing ('directory'): a captured fs.readdirSync result is not executable JavaScript. Read it with fs.readdirSync instead (${url})`)
34
34
  }
35
+ if (format === undefined) {
36
+ throw new Error(`[stasis] cannot execute '${url}': the bundle carries it with no format, as it carries the code Metro builds from source, which is for Metro, not Node`)
37
+ }
35
38
  if (STAT_FORMATS.has(format)) {
36
39
  throw new Error(`[stasis] cannot import '${url}': the bundle carries only a payload-free stat record ('${format}', an fs.lstatSync/statSync capture attesting existence and kind) -- not the file's content. Capture a run that reads or imports it to bundle its bytes.`)
37
40
  }
@@ -562,7 +565,8 @@ function patchCjsResolution() {
562
565
  if (typeof parent?.filename === 'string') {
563
566
  const parentURL = pathToFileURL(parent.filename).toString()
564
567
  if (state.config.full || state.inNodeModules(parentURL)) {
565
- const resolved = state.resolveBundled(parentURL, request)
568
+ // Module._resolveFilename resolves for require(), whose target settles a divergent edge.
569
+ const resolved = state.resolveBundled(parentURL, request, { conditions: ['require'] })
566
570
  if (resolved !== undefined) {
567
571
  assertInfraMatchesBundle(pathToFileURL(resolved).toString())
568
572
  return resolved
package/src/state.js CHANGED
@@ -11,8 +11,9 @@ import { Lockfile } from './lockfile.js'
11
11
  import { parseShard, serializeShard } from './shard.js'
12
12
  import { canonicalizePath, sha512integrity, readFileSyncMaybe, noupsert } from './state-util.js'
13
13
  import { brotliOptions } from './brotli.js'
14
- import { CODE_EXTENSIONS, EMPTY_MODULE_PATH, canObserveExecuteBits, classifyFormat, erasedTypeScriptFormat, fileMapToObject, hasNodeModulesSegment, isBinaryPlist, isNativeArtifact, isPackageString, isPathWithin, isStatFormat, isSubpackage, moduleFileKey, moduleInfo, narrowExecutable, nestedMap, objectToMaps, observeExecutable, pathExt, reconcileFormat, relativeEscapes, sortPaths, splitNodeModulesPath, withMetadataOf } from './util.js'
15
- import { detectRepo, namedManifestOf, packageJSONStat, packageJSONText, packageRepo, readModuleManifest, vendorDirOf, vendoredPackageOf } from './bundle-util.js'
14
+ import { CODE_EXTENSIONS, EMPTY_MODULE_PATH, assertRealPathWithinBase, canObserveExecuteBits, classifyFormat, erasedTypeScriptFormat, fileMapToObject, hasNodeModulesSegment, isBinaryPlist, isNativeArtifact, isPackageString, isPathWithin, isPlainObject, isStatFormat, isSubpackage, moduleFileKey, moduleInfo, narrowExecutable, nestedMap, objectToMaps, observeExecutable, pathExt, reconcileFormat, relativeEscapes, sortPaths, splitNodeModulesPath, toPosix, withMetadataOf } from './util.js'
15
+ import { detectRepo, namedManifestOf, packageJSONStat, packageJSONText, packageRepo, readModuleManifest, scopeManifestOf, vendorDirOf, vendoredPackageOf } from './bundle-util.js'
16
+ import { expandExtra, validationError } from './add.js'
16
17
  import { diskHost } from './host.js'
17
18
  import corePackage from './package.cjs'
18
19
 
@@ -53,6 +54,9 @@ function upsertFormat(map, file, format) {
53
54
  map.set(file, currentFormat === undefined ? format : reconcileFormat(format, currentFormat, file))
54
55
  }
55
56
 
57
+ // A bundled file's integrity as addFile/addFsDir hash it: a 'resource:base64' payload's is its decoded bytes'.
58
+ const bundledIntegrity = (content, format) => sha512integrity(format === 'resource:base64' ? Buffer.from(content, 'base64') : content)
59
+
56
60
  // Loader formats the extension alone decides; `.js`/`.ts` follow the nearest package `type`.
57
61
  const EXT_FORMATS = { __proto__: null, '.json': 'json', '.mjs': 'module', '.cjs': 'commonjs', '.mts': 'module-typescript', '.cts': 'commonjs-typescript' }
58
62
  // With no `type`, Node decides .js/.ts by syntax detection: either variant is possible, the first is the default.
@@ -68,6 +72,25 @@ const INCONSISTENT_PACKAGE_JSON_EXCEPTIONS = [
68
72
  const isInconsistentPackageJsonException = (file) =>
69
73
  INCONSISTENT_PACKAGE_JSON_EXCEPTIONS.some((suffix) => file === suffix || file.endsWith(`/${suffix}`))
70
74
 
75
+ // The resolution context a condition list or imports key ('*', or a ', '-joined list with an
76
+ // optional ' (with: {json})' suffix) asserts: 'import' or 'require'. Null for '*' and for a set
77
+ // naming both or neither (a platform's, a source language's).
78
+ function resolutionContext(conditions) {
79
+ const list = typeof conditions === 'string' ? conditions.split(' (with: ')[0].split(', ') : conditions
80
+ const asImport = list.includes('import')
81
+ if (asImport === list.includes('require')) return null
82
+ return asImport ? 'import' : 'require'
83
+ }
84
+
85
+ // Whether resolving `specifier` reads conditions: a bare one does (a package's `exports`, its own
86
+ // name's included), as does a `#` one (its `imports`); a relative, absolute or URL one never does.
87
+ function readsConditions(specifier) {
88
+ if (typeof specifier !== 'string') return false
89
+ if (specifier.startsWith('#')) return true
90
+ return !(specifier === '.' || specifier === '..' || specifier.startsWith('./') || specifier.startsWith('../') ||
91
+ specifier.startsWith('/') || /^[a-z][a-z\d+.-]*:/i.test(specifier))
92
+ }
93
+
71
94
  // On globalThis via `Symbol.for` so the registry is shared across duplicate stasis-core copies.
72
95
  const STATES_KEY = Symbol.for('@exodus/stasis-core/states')
73
96
  const liveStates = () => (globalThis[STATES_KEY] ??= new Set())
@@ -111,7 +134,9 @@ export class State {
111
134
  #observed = new Set()
112
135
  // file -> consumers that recorded it, for the bundle's informational `reason` field.
113
136
  #reasonFiles = new Map()
114
- #runImported = new Set()
137
+ // 'run' files it imported or fs-read before any plugin attached (its own), and ones it fs-read
138
+ // after one attached: see #reasonClaims.
139
+ #runOwn = new Set()
115
140
  #fsReadPostPlugin = new Set()
116
141
  #pluginAttached = false
117
142
 
@@ -503,6 +528,18 @@ export class State {
503
528
  const withMetadata = withMetadataOf(existing, info)
504
529
  if (withMetadata !== existing) this.modules.set(dir, withMetadata)
505
530
  }
531
+ // A bundle=add run writes these buckets back, and #bundleModules carries only the files a
532
+ // bucket lists: seed them as #absorbLockfile does, else a bundled file this run doesn't
533
+ // load again drops out of the rewritten bundle.
534
+ if (!this.config.writeBundle) continue
535
+ const { files } = this.modules.get(dir)
536
+ for (const [rel, content] of Object.entries(info.files)) {
537
+ const file = moduleFileKey(dir, rel)
538
+ const integrity = bundledIntegrity(content, bundle.formats.get(file))
539
+ noupsert(this.hashes, file, integrity)
540
+ if (!Object.hasOwn(files, rel)) files[rel] = integrity
541
+ assert.equal(files[rel], integrity, `bundle file ${file} conflicts with its recorded hash`)
542
+ }
506
543
  }
507
544
  }
508
545
  }
@@ -554,7 +591,7 @@ export class State {
554
591
 
555
592
  // Verify one resolution edge against an attestation map: exact conditions key first, else accept
556
593
  // only if every condition set agrees on one target. Unknown edges fatal unless tolerateUnknown.
557
- #assertAttestedResolution(attestation, conditions, parent, specifier, file, { what, source = 'lockfile', tolerateUnknown = false }) {
594
+ #assertAttestedResolution(attestation, conditions, parent, specifier, file, { what, source = 'lockfile', tolerateUnknown = false, targetPlatform }) {
558
595
  const edge = `'${specifier}' from ${parent} (${conditions})`
559
596
  let attested = attestation.get(conditions)?.get(parent)?.get(specifier)
560
597
  if (attested === undefined) {
@@ -568,6 +605,11 @@ export class State {
568
605
  assert.ok(targets.size === 1, `${what} resolution ${edge} is attested inconsistently across condition sets in the ${source}`)
569
606
  ;[attested] = targets
570
607
  }
608
+ // A resolution made for one platform checks that platform's target of a per-platform edge.
609
+ if (targetPlatform !== undefined && attested instanceof Map && !(file instanceof Map)) {
610
+ attested = attested.get(targetPlatform)
611
+ assert.ok(attested !== undefined, `${what} resolution ${edge} is not attested for platform '${targetPlatform}' by the ${source}`)
612
+ }
571
613
  // A per-platform edge is a Map<platform, target>: compare structurally (assert.equal is
572
614
  // reference equality).
573
615
  const matches = file instanceof Map && attested instanceof Map
@@ -918,10 +960,10 @@ export class State {
918
960
  // Provenance for the bundle's `reason` field (null = the caller attributes it, see includePackageJson).
919
961
  if (this.config.bundle && reason !== null) {
920
962
  this.#recordReason(reason, file)
921
- // Track HOW 'run' saw this file so #bundleReason can drop files run merely fs-READ post-plugin.
963
+ // Track HOW 'run' saw this file so #reasonClaims can drop files run merely fs-READ post-plugin.
922
964
  if (reason === 'run') {
923
- if (!fsRead) this.#runImported.add(file)
924
- else if (this.#pluginAttached) this.#fsReadPostPlugin.add(file)
965
+ if (fsRead && this.#pluginAttached) this.#fsReadPostPlugin.add(file)
966
+ else this.#runOwn.add(file)
925
967
  }
926
968
  }
927
969
  const rel = relative(dir, file)
@@ -999,21 +1041,76 @@ export class State {
999
1041
  return this.#sidecars
1000
1042
  }
1001
1043
 
1002
- // Record an `fs.readFileSync` capture (--fs). classifyFormat routes the bytes: a concrete format
1003
- // is code, null defers to the loader, and undefined (or a binary plist, whose bytes can't be the
1004
- // UTF-8 code its format implies) is a resource IFF allowlisted, else THROW -- an undeclared file
1005
- // would widen the attested set.
1044
+ // Record an `fs.readFileSync` capture (--fs), carried as #readFileOptions says, else THROW -- an
1045
+ // undeclared file would widen the attested set.
1006
1046
  addFsFile(url, source) {
1007
1047
  assert.ok(Buffer.isBuffer(source), 'addFsFile requires a Buffer source')
1008
1048
  const path = fileURLToPath(url)
1009
- const format = classifyFormat(path, { content: source })
1010
- if (format !== undefined && !isBinaryPlist(path, source)) {
1011
- this.addFile(url, { source, format: format ?? undefined, inferFormat: false, fsRead: true })
1012
- } else if (this.config.resources.has(pathExt(path) || basename(path).toLowerCase())) {
1013
- this.addFile(url, { source, resource: true, fsRead: true })
1014
- } else {
1049
+ const options = this.#readFileOptions(path, source)
1050
+ if (options === null) {
1015
1051
  throw new Error(`addFsFile: ${path} is neither code nor a declared resource; add its extension or filename to the resources allowlist or stop reading it`)
1016
1052
  }
1053
+ this.addFile(url, { source, ...options, fsRead: true })
1054
+ }
1055
+
1056
+ // The addFile options for a file read rather than loaded: classifyFormat routes the bytes -- a
1057
+ // concrete format is code, null defers to the loader, and undefined (or a binary plist, whose bytes
1058
+ // can't be the UTF-8 code its format implies) is a resource IFF in `resources`, else null.
1059
+ #readFileOptions(path, source, resources = this.config.resources) {
1060
+ const format = classifyFormat(path, { content: source })
1061
+ if (format !== undefined && !isBinaryPlist(path, source)) return { format: format ?? undefined, inferFormat: false }
1062
+ if (resources.has(pathExt(path) || basename(path).toLowerCase())) return { resource: true }
1063
+ return null
1064
+ }
1065
+
1066
+ // Attest the files stasis.config.json's `extra` names (expandExtra: paths, directories and globs,
1067
+ // as `stasis add` takes them) beside what the run reached, each carried as an fs read is
1068
+ // (#readFileOptions) unless the run captured it itself, whose record stands. The whole set is
1069
+ // validated before a file is added, every offender named at once. `outputs` are the paths written,
1070
+ // never taken in: by default the ones write() writes. `resources` is the allowlist, the config's by default.
1071
+ includeExtra({ outputs = this.#writeTargets(), resources = this.config.resources } = {}) {
1072
+ if (this.config.extra.length === 0) return
1073
+ // Resolved as write() writes them: a relative one from the cwd.
1074
+ const written = new Set(outputs.map((file) => toPosix(relative(this.root, resolve(file)))))
1075
+ const { files } = expandExtra(this.root, this.config.extra, written)
1076
+ const realRoot = this.#host.realpath(this.root)
1077
+ const missing = []
1078
+ const undeclared = []
1079
+ const nonUtf8 = []
1080
+ const toAdd = []
1081
+ const captured = []
1082
+ for (const [rel, stats] of files) {
1083
+ if (stats === undefined) {
1084
+ missing.push(rel)
1085
+ continue
1086
+ }
1087
+ assertRealPathWithinBase(realRoot, this.root, rel, this.#host)
1088
+ const absolute = resolve(this.root, rel)
1089
+ const url = pathToFileURL(absolute).toString()
1090
+ // A node_modules scope leaves the project's own files out, as it does the run's.
1091
+ if (!this.config.full && !this.inNodeModules(url)) continue
1092
+ // The run's record of a file it captured stands, and `extra` is one more consumer of it.
1093
+ const file = this.#canonicalFile(url)
1094
+ if (this.#filesCapturedThisRun.has(file)) {
1095
+ captured.push(file)
1096
+ continue
1097
+ }
1098
+ const source = this.#host.readFile(absolute)
1099
+ const options = this.#readFileOptions(absolute, source, resources)
1100
+ if (options === null) undeclared.push(rel)
1101
+ else if (!options.resource && !isUtf8(source)) nonUtf8.push({ rel, format: options.format })
1102
+ else toAdd.push({ url, source, options })
1103
+ }
1104
+ if (missing.length + undeclared.length + nonUtf8.length > 0) throw validationError({ missing, undeclared, nonUtf8 }, 'extra')
1105
+ for (const { url, source, options } of toAdd) this.addFile(url, { source, ...options, reason: 'extra' })
1106
+ if (this.config.bundle) for (const file of captured) this.#recordReason('extra', file)
1107
+ }
1108
+
1109
+ // The artifacts write() writes: the lockfile (never a sidecar's) and the bundle(s), as configured.
1110
+ #writeTargets() {
1111
+ const lock = this.config.writeLockfile && !this.#parent ? [this.config.lockFile || join(this.root, FILE_LOCK)] : []
1112
+ const bundles = this.config.writeBundle ? [this.config.bundleFile || join(this.root, FILE_CODE), this.config.resourcesBundleFile] : []
1113
+ return [...lock, ...bundles].filter((file) => file !== undefined)
1017
1114
  }
1018
1115
 
1019
1116
  // Record an `fs.readdirSync` capture: the listing is SORTED for reproducibility and stored as a
@@ -1245,6 +1342,22 @@ export class State {
1245
1342
  if (format) upsertFormat(this.formats, file, format)
1246
1343
  }
1247
1344
 
1345
+ // Under bundle=load, verify a resolution a bundler made on its own (Metro resolves the app's
1346
+ // imports itself, where the loader and the esbuild/webpack plugins take them from the bundle): it
1347
+ // must be the edge the bundle attests, for `platform` where the edge is per-platform. Unknown
1348
+ // edges are tolerated only where addImport tolerates them, for workspace parents in nm scope.
1349
+ assertImport(parentURL, specifier, url, { conditions = '*', importAttributes, platform: targetPlatform } = {}) {
1350
+ assert.ok(this.config.loadBundle, 'assertImport checks a resolution against a loaded bundle (bundle=load)')
1351
+ if (conditions !== '*') assert.ok(Array.isArray(conditions))
1352
+ assert.ok(parentURL, 'assertImport requires a parent')
1353
+ const parent = this.#canonicalFile(parentURL)
1354
+ const file = this.#canonicalFile(url)
1355
+ specifier = this.#canonicalSpecifier(parentURL, specifier)
1356
+ const key = this.#conditionsKey(conditions, importAttributes)
1357
+ const tolerateUnknown = !this.config.full && !hasNodeModulesSegment(parent)
1358
+ this.#assertAttestedResolution(this.imports, key, parent, specifier, file, { what: 'observed', source: 'bundle', tolerateUnknown, targetPlatform })
1359
+ }
1360
+
1248
1361
  getImport(parentURL, specifier, { conditions = '*', importAttributes } = {}) {
1249
1362
  if (conditions !== '*') assert.ok(Array.isArray(conditions))
1250
1363
  assert.ok(parentURL, 'getImport requires a parent') // matches addImport; #canonicalSpecifier needs it
@@ -1256,9 +1369,10 @@ export class State {
1256
1369
  let file = this.imports.get(key)?.get(parent)?.get(specifier)
1257
1370
  if (file === undefined && key !== '*') file = this.imports.get('*')?.get(parent)?.get(specifier)
1258
1371
  if (file === undefined) {
1259
- // The edge may be recorded under a DIFFERENT conditions bucket -- resolveBundled scans every bucket.
1372
+ // The edge may be recorded under a DIFFERENT conditions bucket -- resolveBundled scans every
1373
+ // bucket related to these conditions.
1260
1374
  if (this.config.loadBundle) {
1261
- const abs = this.resolveBundled(parentURL, specifier)
1375
+ const abs = this.resolveBundled(parentURL, specifier, { conditions })
1262
1376
  if (abs !== undefined) return { url: pathToFileURL(abs).toString(), format: this.#loaderFormat(relative(this.root, abs)) }
1263
1377
  }
1264
1378
  // Node's ERR_MODULE_NOT_FOUND shape, not a bare assert: dynamic-import callers guard on that
@@ -1269,7 +1383,7 @@ export class State {
1269
1383
  // context to pick one, so fail closed rather than feed a Map where a path is expected.
1270
1384
  if (typeof file !== 'string') {
1271
1385
  throw Object.assign(
1272
- new Error(`Resolution of '${specifier}' from ${parent} is platform-specific (a --metro multi-platform bundle); it can't be loaded by plain node, build a single-platform bundle to load`),
1386
+ new Error(`Resolution of '${specifier}' from ${parent} is platform-specific (a --metro multi-platform bundle, which is Metro's to build); plain node has no platform to pick one by`),
1273
1387
  { code: 'ERR_STASIS_PLATFORM_SPECIFIC' })
1274
1388
  }
1275
1389
  return { url: pathToFileURL(resolve(this.root, file)).toString(), format: this.#loaderFormat(file) }
@@ -1277,18 +1391,33 @@ export class State {
1277
1391
 
1278
1392
  // Resolve a CJS require() target to a bundled absolute path, or undefined to defer to Node (the
1279
1393
  // hooks.js CJS shim needs this: registerHooks can't intercept Module._resolveFilename). Matches
1280
- // under ANY conditions bucket, since native require gives none; divergent buckets -> defer.
1281
- resolveBundled(parentURL, specifier) {
1394
+ // under the buckets related to `conditions`: every one, except that where conditions decide the
1395
+ // resolution (readsConditions), a key of the other context (see resolutionContext) is another
1396
+ // resolution, never served. Node asks an edge under its own context's set on every version and
1397
+ // code path, the rest varying by flag alone (--conditions, --no-addons, require(esm) off); a
1398
+ // relative edge resolves alike under either, as a capture's replay can ask it (tsx's CJS lane does).
1399
+ // Divergent buckets are settled by those of the lookup's context where they agree -- a
1400
+ // --conditions build's require() and import() targets, each under a key plain node never asks --
1401
+ // else defer.
1402
+ resolveBundled(parentURL, specifier, { conditions = '*' } = {}) {
1282
1403
  const parent = this.#canonicalFileMaybe(parentURL)
1283
1404
  if (parent === undefined) return undefined
1284
1405
  const spec = this.#canonicalSpecifier(parentURL, specifier)
1406
+ const context = resolutionContext(conditions)
1407
+ const contextual = context !== null && readsConditions(spec)
1285
1408
  const matches = new Set()
1286
- for (const [, byParent] of this.imports) {
1409
+ const ownContext = new Set()
1410
+ for (const [key, byParent] of this.imports) {
1287
1411
  const file = byParent.get(parent)?.get(spec)
1288
- if (file !== undefined) matches.add(file)
1289
- }
1290
- if (matches.size !== 1) return undefined
1291
- const [only] = matches
1412
+ if (file === undefined) continue
1413
+ const keyContext = resolutionContext(key)
1414
+ if (contextual && keyContext !== null && keyContext !== context) continue
1415
+ matches.add(file)
1416
+ if (context !== null && keyContext === context) ownContext.add(file)
1417
+ }
1418
+ const candidates = matches.size === 1 ? matches : ownContext
1419
+ if (candidates.size !== 1) return undefined
1420
+ const [only] = candidates
1292
1421
  // Per-platform { platform: file } Map (--metro) has no single path: defer to native, not resolve()'s TypeError.
1293
1422
  return typeof only === 'string' ? resolve(this.root, only) : undefined
1294
1423
  }
@@ -1374,8 +1503,8 @@ export class State {
1374
1503
  return modules
1375
1504
  }
1376
1505
 
1377
- // Files fs-READ after this point that a plugin also bundles are the plugin's, not run's (see
1378
- // #bundleReason). Public, cross-copy.
1506
+ // Files fs-READ after this point for a plugin (one it bundles, or a manifest of a package it
1507
+ // bundles) are the plugin's, not run's (see #reasonClaims). Public, cross-copy.
1379
1508
  markPluginAttached() {
1380
1509
  this.#pluginAttached = true
1381
1510
  }
@@ -1395,24 +1524,52 @@ export class State {
1395
1524
  }
1396
1525
  }
1397
1526
 
1527
+ // Consumer -> the files it claims: #reasonFiles, less what run merely fs-READ after a plugin
1528
+ // attached on a plugin's behalf (never its own: #runOwn). That is a file a plugin also bundles,
1529
+ // which is the plugin's. A package.json fs-read after a plugin attached, of a package a plugin
1530
+ // bundles, is one a bundler reads to resolve (Metro's resolver does) but never bundles itself:
1531
+ // it is that plugin's too, and stays run's only where run has its own claim on it or claims
1532
+ // another file of the package. `extra` names files and bundles none, so it is no plugin here.
1533
+ #reasonClaims() {
1534
+ const pluginFiles = new Set()
1535
+ for (const [who, recorded] of this.#reasonFiles) {
1536
+ if (who !== 'run' && who !== 'extra') for (const file of recorded) pluginFiles.add(file)
1537
+ }
1538
+ const fsReadOnly = (file) => this.#fsReadPostPlugin.has(file) && !this.#runOwn.has(file)
1539
+ const claims = new Map()
1540
+ for (const [who, recorded] of this.#reasonFiles) {
1541
+ claims.set(who, new Set(who === 'run' ? [...recorded].filter((file) => !(fsReadOnly(file) && pluginFiles.has(file))) : recorded))
1542
+ }
1543
+ const run = claims.get('run')
1544
+ if (run === undefined || pluginFiles.size === 0 || this.#fsReadPostPlugin.size === 0) return claims
1545
+ for (const [dir, module] of this.modules) {
1546
+ const rels = Object.keys(module.files)
1547
+ const read = new Set(rels.filter((rel) => basename(rel) === 'package.json').map((rel) => moduleFileKey(dir, rel)).filter((file) => this.#fsReadPostPlugin.has(file) && !pluginFiles.has(file)))
1548
+ if (read.size === 0) continue
1549
+ const files = rels.map((rel) => moduleFileKey(dir, rel)).filter((file) => !read.has(file))
1550
+ const plugins = [...claims].filter(([who, claimed]) => who !== 'run' && who !== 'extra' && files.some((file) => claimed.has(file))).map(([, claimed]) => claimed)
1551
+ if (plugins.length === 0) continue // no plugin bundles the package: run's own read
1552
+ const runClaimsPackage = files.some((file) => run.has(file))
1553
+ for (const file of read) {
1554
+ for (const claimed of plugins) claimed.add(file)
1555
+ if (fsReadOnly(file) && !runClaimsPackage) run.delete(file)
1556
+ }
1557
+ }
1558
+ return claims
1559
+ }
1560
+
1398
1561
  // The bundle's informational `reason` map, restricted to `bundledFiles`; only when >1 consumer
1399
1562
  // contributed. Never attested.
1400
1563
  #bundleReason(bundledFiles) {
1401
1564
  const inBundle = bundledFiles instanceof Set ? bundledFiles : new Set(bundledFiles)
1402
- // A file run merely fs-READ post-plugin that a plugin also bundles is the plugin's, not run's.
1403
- const pluginFiles = new Set()
1404
- for (const [who, recorded] of this.#reasonFiles) {
1405
- if (who !== 'run') for (const file of recorded) pluginFiles.add(file)
1406
- }
1407
- const runOverclaims = (file) =>
1408
- this.#fsReadPostPlugin.has(file) && !this.#runImported.has(file) && pluginFiles.has(file)
1565
+ const claims = this.#reasonClaims()
1409
1566
 
1410
1567
  const reason = {}
1411
1568
  let consumers = 0
1412
1569
  // Sort keys and file lists: the JSON must be byte-reproducible regardless of record order, else
1413
1570
  // #emitBundle's compare-and-skip sees spurious diffs.
1414
- for (const who of [...this.#reasonFiles.keys()].toSorted()) {
1415
- const files = [...this.#reasonFiles.get(who)].filter((file) => inBundle.has(file) && !(who === 'run' && runOverclaims(file)))
1571
+ for (const who of [...claims.keys()].toSorted()) {
1572
+ const files = [...claims.get(who)].filter((file) => inBundle.has(file))
1416
1573
  if (files.length > 0) {
1417
1574
  reason[who] = files.toSorted(sortPaths)
1418
1575
  consumers += 1
@@ -1555,30 +1712,55 @@ export class State {
1555
1712
  }
1556
1713
 
1557
1714
  // Add every bundled module's `<dir>/package.json` (config.packageJSON) even if the run never
1558
- // reached it, so a load/prune can read each dependency's manifest. The skip keys on bundle
1559
- // membership, NOT this.hashes (which also holds lockfile-absorbed entries and is shared by
1560
- // reference across sidecars).
1715
+ // reached it, so a load/prune can read each dependency's manifest, and the nearer one a bundled
1716
+ // file of it has (scopeManifestOf: a `{"type":"module"}` marker such as `esm/package.json`), which
1717
+ // Node and Metro's resolver read for the file. The skip keys on bundle membership, NOT this.hashes
1718
+ // (which also holds lockfile-absorbed entries and is shared by reference across sidecars).
1561
1719
  includePackageJson() {
1562
1720
  // Gather first: addFile mutates this.modules, so don't addFile while iterating it.
1563
1721
  const realRoot = this.#host.realpath(this.root)
1722
+ const claims = this.#reasonClaims()
1723
+ const bundled = (rel) => this.sources.has(rel) || this.resources.has(rel)
1724
+ const found = new Map()
1725
+ const exists = (rel) => found.get(rel) ?? found.set(rel, packageJSONStat(this.#host, resolve(this.root, rel))?.isFile() ?? false).get(rel)
1726
+ // A manifest's bytes and parsed fields, or null where it's gone or malformed (skipped).
1727
+ const read = (rel) => {
1728
+ const buf = readModuleManifest({ baseDir: this.root, realBase: realRoot, rel, host: this.#host })
1729
+ if (!buf) return null
1730
+ try {
1731
+ const pkg = JSON.parse(packageJSONText(buf))
1732
+ return isPlainObject(pkg) ? { buf, pkg } : null
1733
+ } catch {
1734
+ return null
1735
+ }
1736
+ }
1564
1737
  const toAdd = []
1565
1738
  for (const [dir, module] of this.modules) {
1566
- const rel = moduleFileKey(dir, 'package.json')
1567
- if (this.sources.has(rel) || this.resources.has(rel)) continue // already in this bundle
1568
- const buf = readModuleManifest({ baseDir: this.root, realBase: realRoot, rel, host: this.#host })
1569
- if (!buf) continue
1570
- // Only carry a manifest whose on-disk identity still matches the bundled bucket: under
1739
+ const own = moduleFileKey(dir, 'package.json')
1740
+ // Only carry the manifests of a bucket whose on-disk identity still matches: under
1571
1741
  // bundle=add a dep may have drifted, and addFile -> #locateModule would crash on it.
1572
- let pkg
1573
- try { pkg = JSON.parse(buf.toString()) } catch { continue } // malformed manifest for an untouched bucket: skip
1574
- if (pkg?.name !== module.name || pkg?.version !== module.version) continue
1575
- // The manifest rides along BECAUSE some consumer bundled the bucket, so it inherits every
1576
- // consumer that recorded a file of the bucket -- nothing observed the manifest itself, but an
1577
- // unattributed file can't be sorted by provenance downstream. Derived BEFORE the adds below,
1578
- // so one fold's manifest can't count as another bucket's consumer evidence.
1579
- const files = Object.keys(module.files)
1580
- const consumers = [...this.#reasonFiles].filter(([, recorded]) => files.some((f) => recorded.has(moduleFileKey(dir, f)))).map(([who]) => who)
1581
- toAdd.push({ rel, buf, consumers })
1742
+ const manifest = read(own)
1743
+ if (manifest === null || manifest.pkg.name !== module.name || manifest.pkg.version !== module.version) continue
1744
+ // Each manifest -> the files it is the package.json of: the bucket's own, of every file; a
1745
+ // nearer one, of the bundled files below it.
1746
+ const files = Object.keys(module.files).map((f) => moduleFileKey(dir, f))
1747
+ const scopes = new Map([[own, files]])
1748
+ for (const file of files) {
1749
+ const nearest = bundled(file) ? scopeManifestOf(file, dir, exists) : undefined
1750
+ if (nearest !== undefined) (scopes.get(nearest) ?? scopes.set(nearest, []).get(nearest)).push(file)
1751
+ }
1752
+ for (const [rel, of] of scopes) {
1753
+ if (bundled(rel)) continue // already in this bundle
1754
+ const buf = rel === own ? manifest.buf : read(rel)?.buf
1755
+ if (buf === undefined) continue
1756
+ // The manifest rides along BECAUSE some consumer bundled its files, so it inherits every
1757
+ // consumer that claims one (#reasonClaims: not run for a file it merely fs-read for a
1758
+ // plugin) -- nothing observed the manifest itself, but an unattributed file can't be
1759
+ // sorted by provenance downstream. Derived BEFORE the adds below, so one fold's manifest
1760
+ // can't count as another bucket's consumer evidence.
1761
+ const consumers = [...claims].filter(([, claimed]) => of.some((file) => claimed.has(file))).map(([who]) => who)
1762
+ toAdd.push({ rel, buf, consumers })
1763
+ }
1582
1764
  }
1583
1765
  for (const { rel, buf, consumers } of toAdd) {
1584
1766
  this.addFile(pathToFileURL(resolve(this.root, rel)).toString(), { source: buf, reason: null })
@@ -1592,7 +1774,9 @@ export class State {
1592
1774
  this.#backfillObservedResolutions()
1593
1775
  this.#backfillExecutedFiles()
1594
1776
  this.#backfillBeforeWrite()
1595
- // AFTER the backfills, so buckets they create are covered too.
1777
+ // Only when writing (a frozen run verifies what it reached, not `extra`); a sidecar loads no config.
1778
+ if (this.config.writeLockfile || this.config.writeBundle) this.includeExtra()
1779
+ // AFTER the backfills and `extra`, so buckets they create are covered too.
1596
1780
  if (this.config.writeBundle && this.config.packageJSON) this.includePackageJson()
1597
1781
 
1598
1782
  // Sidecars never write the lockfile (parent owns it); they only emit their bundle.
package/src/util.js CHANGED
@@ -1,5 +1,5 @@
1
1
  import { isUtf8 } from 'node:buffer'
2
- import { basename, isAbsolute, join, relative, sep } from 'node:path'
2
+ import { basename, isAbsolute, join, normalize, relative, sep } from 'node:path'
3
3
  import { parseArgs } from 'node:util'
4
4
 
5
5
  import { NODE_FORMATS } from './artifact-util.js'
@@ -68,6 +68,26 @@ export function parseResourcesOption(label, resources) {
68
68
  return out
69
69
  }
70
70
 
71
+ // stasis.config.json's `extra`: paths, directories and glob patterns relative to the project root,
72
+ // taken as `stasis add` takes its arguments, and `!`-prefixed ones excluding what they match
73
+ // (expandExtra). Each must stay within the root.
74
+ export function parseExtraOption(label, extra) {
75
+ if (extra === undefined) return []
76
+ if (!Array.isArray(extra)) {
77
+ throw new TypeError(`${label}: extra must be an array of paths or glob patterns`)
78
+ }
79
+ for (const entry of extra) {
80
+ if (typeof entry !== 'string' || entry === '') {
81
+ throw new TypeError(`${label}: extra entry must be a non-empty string, got ${JSON.stringify(entry)}`)
82
+ }
83
+ if (entry === '!') throw new Error(`${label}: extra entry '!' needs a pattern to exclude (e.g. '!ios/Pods')`)
84
+ if (relativeEscapes(normalize(entry.startsWith('!') ? entry.slice(1) : entry))) {
85
+ throw new Error(`${label}: extra entry '${entry}' must be a path or pattern within the project root`)
86
+ }
87
+ }
88
+ return [...extra]
89
+ }
90
+
71
91
  export const isBrotliQuality = (n) => Number.isInteger(n) && n >= 0 && n <= 11
72
92
 
73
93
  // `${n}` must round-trip to the input, so non-canonical forms ('5.0', '05', ' 5 ') throw.