@exodus/stasis-core 1.0.0-beta.10 → 1.0.0-beta.12

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.10",
3
+ "version": "1.0.0-beta.12",
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.
@@ -197,9 +197,34 @@ export function withMetadataOf(record, other) {
197
197
  return moduleInfo({ ...record, repo, ...merged })
198
198
  }
199
199
 
200
- // A record's `vendored` and `subpackages` as `what` writes them: the entries holding one of `files`, validated.
201
- const carriedDirMetadata = (dir, info, files, what) => fromEntries(Object.keys(DIR_METADATA).map((field) =>
202
- [field, normalizeDirMetadata(field, dir, { ...info, files, [field]: carriedEntries(info[field], files) }, what)]))
200
+ // A record's `vendored` and `subpackages` as `what` writes them: the entries holding one of `files`, validated;
201
+ // a field not in `fields` left out.
202
+ const carriedDirMetadata = (dir, info, files, what, fields) => fromEntries(Object.keys(DIR_METADATA).map((field) =>
203
+ [field, fields.includes(field) ? normalizeDirMetadata(field, dir, { ...info, files, [field]: carriedEntries(info[field], files) }, what) : undefined]))
204
+
205
+ // The packages a module map records, for what looks at each of them (`stasis audit`): every record, as it is,
206
+ // and after a dependency's, each `vendored` copy in it as a record of its own, at the copy's directory in the
207
+ // project (`node_modules/next/dist/compiled/react-is`): its `name` and `version`, its host's `ecosystem`,
208
+ // `vendoredIn` its host's dir, and `files`, those the copy holds (each counted for the deepest entry holding
209
+ // it), relative to that directory. A host keeps all its files, the copies' too: they are shipped as its.
210
+ // File values are carried over as they are (a contents-free bundle's locked ones unread).
211
+ export function* packageRecords(modules) {
212
+ for (const [dir, record] of modules) {
213
+ yield [dir, record]
214
+ if (record.vendored === undefined) continue
215
+ const held = new Map()
216
+ for (const rel of Object.keys(record.files)) {
217
+ const sub = entryDirOf(record.vendored, rel)
218
+ if (sub === undefined) continue
219
+ if (!held.has(sub)) held.set(sub, Object.create(null))
220
+ Object.defineProperty(held.get(sub), rel.slice(sub.length + 1), Object.getOwnPropertyDescriptor(record.files, rel))
221
+ }
222
+ for (const [sub, files] of held) {
223
+ const { name, version } = record.vendored[sub]
224
+ yield [moduleFileKey(dir, sub), { name, version, ecosystem: record.ecosystem, vendoredIn: dir, files }]
225
+ }
226
+ }
227
+ }
203
228
 
204
229
  // A parsed bucket `dir` of a `what` artifact: an absent version has one spelling (a literal null folds
205
230
  // into undefined so identity comparisons and JSON round-trips can't split on it), `repo`, `vendored` and
@@ -455,9 +480,11 @@ export function serializeImports(imports) {
455
480
 
456
481
  // A module map as the serialized `modules` (node_modules buckets) and `sources` (the rest) objects
457
482
  // of a `what` artifact, buckets and files path-sorted so the bytes are canonical. Each record's
458
- // `vendored` and `subpackages` keep the entries holding one of the files it carries. `metadata: false`
459
- // leaves each record's `repo`, `vendored` and `subpackages` out: metadata, which a lockfile never carries.
460
- export function groupModules(modules, { skipEmpty = false, metadata = true, what } = {}) {
483
+ // `vendored` and `subpackages` keep the entries holding one of the files it carries. `metadata` names the
484
+ // metadata fields written (a lockfile carries `vendored` alone, so it can be audited on its own), or is
485
+ // `true` for every one and `false` for none, as the option once was.
486
+ export function groupModules(modules, { skipEmpty = false, metadata: written = true, what } = {}) {
487
+ const metadata = written === true ? ['repo', ...Object.keys(DIR_METADATA)] : written === false ? [] : written
461
488
  const grouped = { modules: [], sources: [] }
462
489
  for (const [dir, info] of modules) {
463
490
  if (skipEmpty && Object.keys(info.files).length === 0) continue
@@ -466,8 +493,8 @@ export function groupModules(modules, { skipEmpty = false, metadata = true, what
466
493
  const files = fromEntries(Object.entries(info.files).toSorted(byPath))
467
494
  grouped[inNodeModules ? 'modules' : 'sources'].push([dir, moduleInfo({
468
495
  ...info,
469
- repo: metadata ? normalizeModuleRepo(dir, info, what) : undefined,
470
- ...(metadata ? carriedDirMetadata(dir, info, files, what) : { vendored: undefined, subpackages: undefined }),
496
+ repo: metadata.includes('repo') ? normalizeModuleRepo(dir, info, what) : undefined,
497
+ ...carriedDirMetadata(dir, info, files, what, metadata),
471
498
  files,
472
499
  })])
473
500
  }
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/lockfile.js CHANGED
@@ -4,8 +4,10 @@ const VERSION = 0
4
4
 
5
5
  const duplicateKey = duplicateKeyError('lockfile', 'lockfile (lock=replace)')
6
6
 
7
- // A record as a lockfile holds it: without `repo`, `vendored` and `subpackages`, metadata a bundle carries and nothing attests.
8
- const lockRecord = ({ repo: _repo, vendored: _vendored, subpackages: _subpackages, ...info }) => info
7
+ // A record as a lockfile holds it: without `repo` and `subpackages`, metadata a bundle carries and nothing attests.
8
+ // `vendored` it keeps, unattested too, so the copies a dependency ships can be audited from a lockfile alone.
9
+ const LOCK_METADATA = ['vendored']
10
+ const lockRecord = ({ repo: _repo, subpackages: _subpackages, ...info }) => info
9
11
 
10
12
  export class Lockfile {
11
13
  static VERSION = VERSION
@@ -81,7 +83,7 @@ export class Lockfile {
81
83
  serialize() {
82
84
  // Never write an artifact that parse would reject.
83
85
  flatFileKeys(this.modules, 'lockfile', duplicateKey)
84
- const { modules, sources } = groupModules(this.modules, { metadata: false, what: 'lockfile' })
86
+ const { modules, sources } = groupModules(this.modules, { metadata: LOCK_METADATA, what: 'lockfile' })
85
87
  const store = { version: this.version, config: this.config }
86
88
  if (this.config.scope === 'full') Object.assign(store, { entries: serializeEntries(this.entries, 'lockfile'), sources })
87
89
  store.modules = modules
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'
14
+ import { CODE_EXTENSIONS, EMPTY_MODULE_PATH, assertRealPathWithinBase, canObserveExecuteBits, classifyFormat, erasedTypeScriptFormat, fileMapToObject, hasNodeModulesSegment, isBinaryPlist, isNativeArtifact, isPackageString, isPathWithin, isStatFormat, isSubpackage, moduleFileKey, moduleInfo, narrowExecutable, nestedMap, objectToMaps, observeExecutable, pathExt, reconcileFormat, relativeEscapes, sortPaths, splitNodeModulesPath, toPosix, withMetadataOf } from './util.js'
15
15
  import { detectRepo, namedManifestOf, packageJSONStat, packageJSONText, packageRepo, readModuleManifest, 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
 
@@ -68,6 +69,25 @@ const INCONSISTENT_PACKAGE_JSON_EXCEPTIONS = [
68
69
  const isInconsistentPackageJsonException = (file) =>
69
70
  INCONSISTENT_PACKAGE_JSON_EXCEPTIONS.some((suffix) => file === suffix || file.endsWith(`/${suffix}`))
70
71
 
72
+ // The resolution context a condition list or imports key ('*', or a ', '-joined list with an
73
+ // optional ' (with: {json})' suffix) asserts: 'import' or 'require'. Null for '*' and for a set
74
+ // naming both or neither (a platform's, a source language's).
75
+ function resolutionContext(conditions) {
76
+ const list = typeof conditions === 'string' ? conditions.split(' (with: ')[0].split(', ') : conditions
77
+ const asImport = list.includes('import')
78
+ if (asImport === list.includes('require')) return null
79
+ return asImport ? 'import' : 'require'
80
+ }
81
+
82
+ // Whether resolving `specifier` reads conditions: a bare one does (a package's `exports`, its own
83
+ // name's included), as does a `#` one (its `imports`); a relative, absolute or URL one never does.
84
+ function readsConditions(specifier) {
85
+ if (typeof specifier !== 'string') return false
86
+ if (specifier.startsWith('#')) return true
87
+ return !(specifier === '.' || specifier === '..' || specifier.startsWith('./') || specifier.startsWith('../') ||
88
+ specifier.startsWith('/') || /^[a-z][a-z\d+.-]*:/i.test(specifier))
89
+ }
90
+
71
91
  // On globalThis via `Symbol.for` so the registry is shared across duplicate stasis-core copies.
72
92
  const STATES_KEY = Symbol.for('@exodus/stasis-core/states')
73
93
  const liveStates = () => (globalThis[STATES_KEY] ??= new Set())
@@ -111,7 +131,9 @@ export class State {
111
131
  #observed = new Set()
112
132
  // file -> consumers that recorded it, for the bundle's informational `reason` field.
113
133
  #reasonFiles = new Map()
114
- #runImported = new Set()
134
+ // 'run' files it imported or fs-read before any plugin attached (its own), and ones it fs-read
135
+ // after one attached: see #reasonClaims.
136
+ #runOwn = new Set()
115
137
  #fsReadPostPlugin = new Set()
116
138
  #pluginAttached = false
117
139
 
@@ -554,7 +576,7 @@ export class State {
554
576
 
555
577
  // Verify one resolution edge against an attestation map: exact conditions key first, else accept
556
578
  // 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 }) {
579
+ #assertAttestedResolution(attestation, conditions, parent, specifier, file, { what, source = 'lockfile', tolerateUnknown = false, targetPlatform }) {
558
580
  const edge = `'${specifier}' from ${parent} (${conditions})`
559
581
  let attested = attestation.get(conditions)?.get(parent)?.get(specifier)
560
582
  if (attested === undefined) {
@@ -568,6 +590,11 @@ export class State {
568
590
  assert.ok(targets.size === 1, `${what} resolution ${edge} is attested inconsistently across condition sets in the ${source}`)
569
591
  ;[attested] = targets
570
592
  }
593
+ // A resolution made for one platform checks that platform's target of a per-platform edge.
594
+ if (targetPlatform !== undefined && attested instanceof Map && !(file instanceof Map)) {
595
+ attested = attested.get(targetPlatform)
596
+ assert.ok(attested !== undefined, `${what} resolution ${edge} is not attested for platform '${targetPlatform}' by the ${source}`)
597
+ }
571
598
  // A per-platform edge is a Map<platform, target>: compare structurally (assert.equal is
572
599
  // reference equality).
573
600
  const matches = file instanceof Map && attested instanceof Map
@@ -918,10 +945,10 @@ export class State {
918
945
  // Provenance for the bundle's `reason` field (null = the caller attributes it, see includePackageJson).
919
946
  if (this.config.bundle && reason !== null) {
920
947
  this.#recordReason(reason, file)
921
- // Track HOW 'run' saw this file so #bundleReason can drop files run merely fs-READ post-plugin.
948
+ // Track HOW 'run' saw this file so #reasonClaims can drop files run merely fs-READ post-plugin.
922
949
  if (reason === 'run') {
923
- if (!fsRead) this.#runImported.add(file)
924
- else if (this.#pluginAttached) this.#fsReadPostPlugin.add(file)
950
+ if (fsRead && this.#pluginAttached) this.#fsReadPostPlugin.add(file)
951
+ else this.#runOwn.add(file)
925
952
  }
926
953
  }
927
954
  const rel = relative(dir, file)
@@ -999,21 +1026,76 @@ export class State {
999
1026
  return this.#sidecars
1000
1027
  }
1001
1028
 
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.
1029
+ // Record an `fs.readFileSync` capture (--fs), carried as #readFileOptions says, else THROW -- an
1030
+ // undeclared file would widen the attested set.
1006
1031
  addFsFile(url, source) {
1007
1032
  assert.ok(Buffer.isBuffer(source), 'addFsFile requires a Buffer source')
1008
1033
  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 {
1034
+ const options = this.#readFileOptions(path, source)
1035
+ if (options === null) {
1015
1036
  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
1037
  }
1038
+ this.addFile(url, { source, ...options, fsRead: true })
1039
+ }
1040
+
1041
+ // The addFile options for a file read rather than loaded: classifyFormat routes the bytes -- a
1042
+ // concrete format is code, null defers to the loader, and undefined (or a binary plist, whose bytes
1043
+ // can't be the UTF-8 code its format implies) is a resource IFF in `resources`, else null.
1044
+ #readFileOptions(path, source, resources = this.config.resources) {
1045
+ const format = classifyFormat(path, { content: source })
1046
+ if (format !== undefined && !isBinaryPlist(path, source)) return { format: format ?? undefined, inferFormat: false }
1047
+ if (resources.has(pathExt(path) || basename(path).toLowerCase())) return { resource: true }
1048
+ return null
1049
+ }
1050
+
1051
+ // Attest the files stasis.config.json's `extra` names (expandExtra: paths, directories and globs,
1052
+ // as `stasis add` takes them) beside what the run reached, each carried as an fs read is
1053
+ // (#readFileOptions) unless the run captured it itself, whose record stands. The whole set is
1054
+ // validated before a file is added, every offender named at once. `outputs` are the paths written,
1055
+ // never taken in: by default the ones write() writes. `resources` is the allowlist, the config's by default.
1056
+ includeExtra({ outputs = this.#writeTargets(), resources = this.config.resources } = {}) {
1057
+ if (this.config.extra.length === 0) return
1058
+ // Resolved as write() writes them: a relative one from the cwd.
1059
+ const written = new Set(outputs.map((file) => toPosix(relative(this.root, resolve(file)))))
1060
+ const { files } = expandExtra(this.root, this.config.extra, written)
1061
+ const realRoot = this.#host.realpath(this.root)
1062
+ const missing = []
1063
+ const undeclared = []
1064
+ const nonUtf8 = []
1065
+ const toAdd = []
1066
+ const captured = []
1067
+ for (const [rel, stats] of files) {
1068
+ if (stats === undefined) {
1069
+ missing.push(rel)
1070
+ continue
1071
+ }
1072
+ assertRealPathWithinBase(realRoot, this.root, rel, this.#host)
1073
+ const absolute = resolve(this.root, rel)
1074
+ const url = pathToFileURL(absolute).toString()
1075
+ // A node_modules scope leaves the project's own files out, as it does the run's.
1076
+ if (!this.config.full && !this.inNodeModules(url)) continue
1077
+ // The run's record of a file it captured stands, and `extra` is one more consumer of it.
1078
+ const file = this.#canonicalFile(url)
1079
+ if (this.#filesCapturedThisRun.has(file)) {
1080
+ captured.push(file)
1081
+ continue
1082
+ }
1083
+ const source = this.#host.readFile(absolute)
1084
+ const options = this.#readFileOptions(absolute, source, resources)
1085
+ if (options === null) undeclared.push(rel)
1086
+ else if (!options.resource && !isUtf8(source)) nonUtf8.push({ rel, format: options.format })
1087
+ else toAdd.push({ url, source, options })
1088
+ }
1089
+ if (missing.length + undeclared.length + nonUtf8.length > 0) throw validationError({ missing, undeclared, nonUtf8 }, 'extra')
1090
+ for (const { url, source, options } of toAdd) this.addFile(url, { source, ...options, reason: 'extra' })
1091
+ if (this.config.bundle) for (const file of captured) this.#recordReason('extra', file)
1092
+ }
1093
+
1094
+ // The artifacts write() writes: the lockfile (never a sidecar's) and the bundle(s), as configured.
1095
+ #writeTargets() {
1096
+ const lock = this.config.writeLockfile && !this.#parent ? [this.config.lockFile || join(this.root, FILE_LOCK)] : []
1097
+ const bundles = this.config.writeBundle ? [this.config.bundleFile || join(this.root, FILE_CODE), this.config.resourcesBundleFile] : []
1098
+ return [...lock, ...bundles].filter((file) => file !== undefined)
1017
1099
  }
1018
1100
 
1019
1101
  // Record an `fs.readdirSync` capture: the listing is SORTED for reproducibility and stored as a
@@ -1245,6 +1327,22 @@ export class State {
1245
1327
  if (format) upsertFormat(this.formats, file, format)
1246
1328
  }
1247
1329
 
1330
+ // Under bundle=load, verify a resolution a bundler made on its own (Metro resolves the app's
1331
+ // imports itself, where the loader and the esbuild/webpack plugins take them from the bundle): it
1332
+ // must be the edge the bundle attests, for `platform` where the edge is per-platform. Unknown
1333
+ // edges are tolerated only where addImport tolerates them, for workspace parents in nm scope.
1334
+ assertImport(parentURL, specifier, url, { conditions = '*', importAttributes, platform: targetPlatform } = {}) {
1335
+ assert.ok(this.config.loadBundle, 'assertImport checks a resolution against a loaded bundle (bundle=load)')
1336
+ if (conditions !== '*') assert.ok(Array.isArray(conditions))
1337
+ assert.ok(parentURL, 'assertImport requires a parent')
1338
+ const parent = this.#canonicalFile(parentURL)
1339
+ const file = this.#canonicalFile(url)
1340
+ specifier = this.#canonicalSpecifier(parentURL, specifier)
1341
+ const key = this.#conditionsKey(conditions, importAttributes)
1342
+ const tolerateUnknown = !this.config.full && !hasNodeModulesSegment(parent)
1343
+ this.#assertAttestedResolution(this.imports, key, parent, specifier, file, { what: 'observed', source: 'bundle', tolerateUnknown, targetPlatform })
1344
+ }
1345
+
1248
1346
  getImport(parentURL, specifier, { conditions = '*', importAttributes } = {}) {
1249
1347
  if (conditions !== '*') assert.ok(Array.isArray(conditions))
1250
1348
  assert.ok(parentURL, 'getImport requires a parent') // matches addImport; #canonicalSpecifier needs it
@@ -1256,9 +1354,10 @@ export class State {
1256
1354
  let file = this.imports.get(key)?.get(parent)?.get(specifier)
1257
1355
  if (file === undefined && key !== '*') file = this.imports.get('*')?.get(parent)?.get(specifier)
1258
1356
  if (file === undefined) {
1259
- // The edge may be recorded under a DIFFERENT conditions bucket -- resolveBundled scans every bucket.
1357
+ // The edge may be recorded under a DIFFERENT conditions bucket -- resolveBundled scans every
1358
+ // bucket related to these conditions.
1260
1359
  if (this.config.loadBundle) {
1261
- const abs = this.resolveBundled(parentURL, specifier)
1360
+ const abs = this.resolveBundled(parentURL, specifier, { conditions })
1262
1361
  if (abs !== undefined) return { url: pathToFileURL(abs).toString(), format: this.#loaderFormat(relative(this.root, abs)) }
1263
1362
  }
1264
1363
  // Node's ERR_MODULE_NOT_FOUND shape, not a bare assert: dynamic-import callers guard on that
@@ -1269,7 +1368,7 @@ export class State {
1269
1368
  // context to pick one, so fail closed rather than feed a Map where a path is expected.
1270
1369
  if (typeof file !== 'string') {
1271
1370
  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`),
1371
+ 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
1372
  { code: 'ERR_STASIS_PLATFORM_SPECIFIC' })
1274
1373
  }
1275
1374
  return { url: pathToFileURL(resolve(this.root, file)).toString(), format: this.#loaderFormat(file) }
@@ -1277,18 +1376,33 @@ export class State {
1277
1376
 
1278
1377
  // Resolve a CJS require() target to a bundled absolute path, or undefined to defer to Node (the
1279
1378
  // 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) {
1379
+ // under the buckets related to `conditions`: every one, except that where conditions decide the
1380
+ // resolution (readsConditions), a key of the other context (see resolutionContext) is another
1381
+ // resolution, never served. Node asks an edge under its own context's set on every version and
1382
+ // code path, the rest varying by flag alone (--conditions, --no-addons, require(esm) off); a
1383
+ // relative edge resolves alike under either, as a capture's replay can ask it (tsx's CJS lane does).
1384
+ // Divergent buckets are settled by those of the lookup's context where they agree -- a
1385
+ // --conditions build's require() and import() targets, each under a key plain node never asks --
1386
+ // else defer.
1387
+ resolveBundled(parentURL, specifier, { conditions = '*' } = {}) {
1282
1388
  const parent = this.#canonicalFileMaybe(parentURL)
1283
1389
  if (parent === undefined) return undefined
1284
1390
  const spec = this.#canonicalSpecifier(parentURL, specifier)
1391
+ const context = resolutionContext(conditions)
1392
+ const contextual = context !== null && readsConditions(spec)
1285
1393
  const matches = new Set()
1286
- for (const [, byParent] of this.imports) {
1394
+ const ownContext = new Set()
1395
+ for (const [key, byParent] of this.imports) {
1287
1396
  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
1397
+ if (file === undefined) continue
1398
+ const keyContext = resolutionContext(key)
1399
+ if (contextual && keyContext !== null && keyContext !== context) continue
1400
+ matches.add(file)
1401
+ if (context !== null && keyContext === context) ownContext.add(file)
1402
+ }
1403
+ const candidates = matches.size === 1 ? matches : ownContext
1404
+ if (candidates.size !== 1) return undefined
1405
+ const [only] = candidates
1292
1406
  // Per-platform { platform: file } Map (--metro) has no single path: defer to native, not resolve()'s TypeError.
1293
1407
  return typeof only === 'string' ? resolve(this.root, only) : undefined
1294
1408
  }
@@ -1374,8 +1488,8 @@ export class State {
1374
1488
  return modules
1375
1489
  }
1376
1490
 
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.
1491
+ // Files fs-READ after this point for a plugin (one it bundles, or a manifest of a package it
1492
+ // bundles) are the plugin's, not run's (see #reasonClaims). Public, cross-copy.
1379
1493
  markPluginAttached() {
1380
1494
  this.#pluginAttached = true
1381
1495
  }
@@ -1395,24 +1509,52 @@ export class State {
1395
1509
  }
1396
1510
  }
1397
1511
 
1512
+ // Consumer -> the files it claims: #reasonFiles, less what run merely fs-READ after a plugin
1513
+ // attached on a plugin's behalf (never its own: #runOwn). That is a file a plugin also bundles,
1514
+ // which is the plugin's. A package.json fs-read after a plugin attached, of a package a plugin
1515
+ // bundles, is one a bundler reads to resolve (Metro's resolver does) but never bundles itself:
1516
+ // it is that plugin's too, and stays run's only where run has its own claim on it or claims
1517
+ // another file of the package. `extra` names files and bundles none, so it is no plugin here.
1518
+ #reasonClaims() {
1519
+ const pluginFiles = new Set()
1520
+ for (const [who, recorded] of this.#reasonFiles) {
1521
+ if (who !== 'run' && who !== 'extra') for (const file of recorded) pluginFiles.add(file)
1522
+ }
1523
+ const fsReadOnly = (file) => this.#fsReadPostPlugin.has(file) && !this.#runOwn.has(file)
1524
+ const claims = new Map()
1525
+ for (const [who, recorded] of this.#reasonFiles) {
1526
+ claims.set(who, new Set(who === 'run' ? [...recorded].filter((file) => !(fsReadOnly(file) && pluginFiles.has(file))) : recorded))
1527
+ }
1528
+ const run = claims.get('run')
1529
+ if (run === undefined || pluginFiles.size === 0 || this.#fsReadPostPlugin.size === 0) return claims
1530
+ for (const [dir, module] of this.modules) {
1531
+ const rels = Object.keys(module.files)
1532
+ 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)))
1533
+ if (read.size === 0) continue
1534
+ const files = rels.map((rel) => moduleFileKey(dir, rel)).filter((file) => !read.has(file))
1535
+ const plugins = [...claims].filter(([who, claimed]) => who !== 'run' && who !== 'extra' && files.some((file) => claimed.has(file))).map(([, claimed]) => claimed)
1536
+ if (plugins.length === 0) continue // no plugin bundles the package: run's own read
1537
+ const runClaimsPackage = files.some((file) => run.has(file))
1538
+ for (const file of read) {
1539
+ for (const claimed of plugins) claimed.add(file)
1540
+ if (fsReadOnly(file) && !runClaimsPackage) run.delete(file)
1541
+ }
1542
+ }
1543
+ return claims
1544
+ }
1545
+
1398
1546
  // The bundle's informational `reason` map, restricted to `bundledFiles`; only when >1 consumer
1399
1547
  // contributed. Never attested.
1400
1548
  #bundleReason(bundledFiles) {
1401
1549
  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)
1550
+ const claims = this.#reasonClaims()
1409
1551
 
1410
1552
  const reason = {}
1411
1553
  let consumers = 0
1412
1554
  // Sort keys and file lists: the JSON must be byte-reproducible regardless of record order, else
1413
1555
  // #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)))
1556
+ for (const who of [...claims.keys()].toSorted()) {
1557
+ const files = [...claims.get(who)].filter((file) => inBundle.has(file))
1416
1558
  if (files.length > 0) {
1417
1559
  reason[who] = files.toSorted(sortPaths)
1418
1560
  consumers += 1
@@ -1561,6 +1703,7 @@ export class State {
1561
1703
  includePackageJson() {
1562
1704
  // Gather first: addFile mutates this.modules, so don't addFile while iterating it.
1563
1705
  const realRoot = this.#host.realpath(this.root)
1706
+ const claims = this.#reasonClaims()
1564
1707
  const toAdd = []
1565
1708
  for (const [dir, module] of this.modules) {
1566
1709
  const rel = moduleFileKey(dir, 'package.json')
@@ -1573,11 +1716,12 @@ export class State {
1573
1716
  try { pkg = JSON.parse(buf.toString()) } catch { continue } // malformed manifest for an untouched bucket: skip
1574
1717
  if (pkg?.name !== module.name || pkg?.version !== module.version) continue
1575
1718
  // 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.
1719
+ // consumer that claims a file of the bucket (#reasonClaims: not run for a file it merely
1720
+ // fs-read for a plugin) -- nothing observed the manifest itself, but an unattributed file
1721
+ // can't be sorted by provenance downstream. Derived BEFORE the adds below, so one fold's
1722
+ // manifest can't count as another bucket's consumer evidence.
1579
1723
  const files = Object.keys(module.files)
1580
- const consumers = [...this.#reasonFiles].filter(([, recorded]) => files.some((f) => recorded.has(moduleFileKey(dir, f)))).map(([who]) => who)
1724
+ const consumers = [...claims].filter(([, claimed]) => files.some((f) => claimed.has(moduleFileKey(dir, f)))).map(([who]) => who)
1581
1725
  toAdd.push({ rel, buf, consumers })
1582
1726
  }
1583
1727
  for (const { rel, buf, consumers } of toAdd) {
@@ -1592,7 +1736,9 @@ export class State {
1592
1736
  this.#backfillObservedResolutions()
1593
1737
  this.#backfillExecutedFiles()
1594
1738
  this.#backfillBeforeWrite()
1595
- // AFTER the backfills, so buckets they create are covered too.
1739
+ // Only when writing (a frozen run verifies what it reached, not `extra`); a sidecar loads no config.
1740
+ if (this.config.writeLockfile || this.config.writeBundle) this.includeExtra()
1741
+ // AFTER the backfills and `extra`, so buckets they create are covered too.
1596
1742
  if (this.config.writeBundle && this.config.packageJSON) this.includePackageJson()
1597
1743
 
1598
1744
  // 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.