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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/src/bundle.js CHANGED
@@ -1,9 +1,12 @@
1
1
  import {
2
- KNOWN_FORMATS,
3
2
  assert,
4
- fileMapToObject,
3
+ assertArtifactPath,
4
+ canonicalFileKey,
5
+ duplicateKeyError,
5
6
  fileSetToObject,
6
7
  fromEntries,
8
+ flatFileKeys,
9
+ groupModules,
7
10
  hasNodeModulesSegment,
8
11
  isPlainObject,
9
12
  mergeFormatMaps,
@@ -11,37 +14,95 @@ import {
11
14
  mergeExecutableSets,
12
15
  mergeModuleMaps,
13
16
  moduleFileKey,
14
- objectToMaps,
17
+ normalizeBlock,
18
+ normalizeModule,
19
+ normalizeRepo,
20
+ parseEntries,
15
21
  parseExecutable,
22
+ parseFormats,
23
+ parseImports,
24
+ serializeEntries,
16
25
  serializeExecutable,
26
+ serializeFormats,
27
+ serializeImports,
17
28
  posixPathEscapes,
18
- sortPaths,
29
+ REPO_FIELDS,
30
+ sameGithub,
19
31
  splitNodeModulesPath,
20
32
  } from './artifact-util.js'
21
33
 
22
34
  const VERSION = 1
23
35
  const LEGACY_VERSION = 0
24
36
 
25
- const normalize = ({ name, version, ecosystem, files }) => {
26
- assert(ecosystem === undefined || typeof ecosystem === 'string')
27
- return { name, version, ...(ecosystem === undefined ? {} : { ecosystem }), files: fromEntries(Object.entries(files)) }
28
- }
37
+ const duplicateKey = duplicateKeyError('bundle', 'artifact (bundle=replace)')
29
38
 
39
+ // A v0 path's bucket split; '' and '.' both spell the root listing (rel '').
30
40
  const inferModuleDir = (path) =>
31
- splitNodeModulesPath(path) ?? { dir: '.', rel: path, name: null }
41
+ splitNodeModulesPath(path) ?? { dir: '.', rel: path === '.' ? '' : path, name: null }
42
+
43
+ function contentsLocked() {
44
+ throw new Error('bundle: file contents are not retained by this contents-free Bundle')
45
+ }
46
+
47
+ // Each file stays an own enumerable key, but reading its contents throws; each value must be a placeholder.
48
+ const lockModule = (dir, { files, ...info }) => {
49
+ const locked = Object.create(null)
50
+ for (const [rel, value] of Object.entries(files)) {
51
+ if (typeof value !== 'symbol') assert(false, `bundle: file '${moduleFileKey(dir, rel)}' is not a placeholder`)
52
+ Object.defineProperty(locked, rel, { get: contentsLocked, enumerable: true })
53
+ }
54
+ return { ...info, files: Object.freeze(locked) }
55
+ }
32
56
 
57
+ // Union of the informational `reason` maps in canonical form: consumers sorted, each file list
58
+ // deduped and path-sorted. Canonical even when only one side is given, so a fresh withReason()
59
+ // stamp or a parsed artifact can't leak discovery/record order into the map (state's
60
+ // #bundleReason sorts the same way). A non-array list (unvalidated -- informational) is dropped.
33
61
  const mergeReason = (a, b) => {
34
- if (a === undefined) return b
35
- if (b === undefined) return a
36
- const out = {}
62
+ if (a === undefined && b === undefined) return undefined
63
+ // Accumulated in a Map: on a plain object a '__proto__' consumer key would hit the prototype.
64
+ const merged = new Map()
37
65
  for (const src of [a, b]) {
38
- for (const [consumer, files] of Object.entries(src)) {
39
- out[consumer] = fileSetToObject(new Set([...(out[consumer] ?? []), ...files]))
66
+ for (const [consumer, files] of Object.entries(src ?? {})) {
67
+ if (!Array.isArray(files)) continue
68
+ let set = merged.get(consumer)
69
+ if (set === undefined) merged.set(consumer, (set = new Set()))
70
+ for (const file of files) set.add(file)
40
71
  }
41
72
  }
42
- return out
73
+ return fromEntries([...merged.keys()].toSorted().map((c) => [c, fileSetToObject(merged.get(c))]))
74
+ }
75
+
76
+ // Validate one `repo` field without throwing.
77
+ export const isValidRepoField = (key, value) => Object.hasOwn(REPO_FIELDS, key) && REPO_FIELDS[key](value)
78
+
79
+ // `repo` of a bundle plus one added to it: only agreeing fields survive, and none if `github` differs.
80
+ export const mergeRepo = (a, b) => {
81
+ if (a?.github === undefined || !sameGithub(a.github, b?.github)) return undefined
82
+ const kept = Object.keys(REPO_FIELDS).filter((key) => a[key] !== undefined && (key === 'github' || a[key] === b[key]))
83
+ return fromEntries(kept.map((key) => [key, a[key]]))
84
+ }
85
+
86
+ // A parsed header `repo`, an older stasis's `root: true` read as unknown: it recorded one from a
87
+ // package.json's claim as well as from a git work tree.
88
+ const parsedRepo = (repo) => {
89
+ if (!isPlainObject(repo) || repo.root !== true || Object.hasOwn(repo, 'directory')) return repo
90
+ const { root: _root, ...rest } = repo
91
+ return rest
43
92
  }
44
93
 
94
+ // A package name or version: characters some ecosystem uses there (npm's legacy `~'!()*` too), so not space or `"#$%&,:;<=>?[\]^`{|}`.
95
+ const isPackageString = (v) => typeof v === 'string' && /^[\w.+@/~'!()*-]+$/u.test(v)
96
+ const PACKAGE_BLOCK = { name: isPackageString, version: isPackageString }
97
+ // One block per ecosystem, named as a module's `ecosystem` is.
98
+ const PACKAGE_FIELDS = { npm: PACKAGE_BLOCK, composer: PACKAGE_BLOCK, cargo: PACKAGE_BLOCK }
99
+
100
+ // `package` of a bundle plus one added to it: per ecosystem, only agreeing fields survive, and none unless `name` does.
101
+ const mergePackage = (a, b) => fromEntries(Object.keys(PACKAGE_FIELDS).map((ecosystem) => {
102
+ const [x, y] = [a?.[ecosystem], b?.[ecosystem]]
103
+ return [ecosystem, x?.name !== undefined && x.name === y?.name ? fromEntries(Object.entries(x).filter(([key, value]) => value === y[key])) : undefined]
104
+ }))
105
+
45
106
  // JSON shape of stasis.code.br; callers own the brotli wrap. parse accepts legacy v0 and v1, serialize always writes v1.
46
107
  export class Bundle {
47
108
  static VERSION = VERSION
@@ -56,8 +117,24 @@ export class Bundle {
56
117
  executable
57
118
  // Informational only, NOT attested -- never consulted for verification.
58
119
  reason
120
+ // Informational, not attested, never in a lockfile; validated on every assignment, and frozen.
121
+ #repo
122
+ get repo() {
123
+ return this.#repo
124
+ }
125
+ set repo(repo) {
126
+ this.#repo = normalizeRepo(repo)
127
+ }
128
+ // `{ npm | composer | cargo: { name, version } }`: the package this bundle is; as `repo`, but never set by a build.
129
+ #package
130
+ get package() {
131
+ return this.#package
132
+ }
133
+ set package(pkg) {
134
+ this.#package = normalizeBlock(pkg, PACKAGE_FIELDS, 'bundle package')
135
+ }
59
136
 
60
- constructor({ config = { scope: 'full' }, entries, modules, formats, imports, executable, reason, version = VERSION } = {}) {
137
+ constructor({ config = { scope: 'full' }, entries, modules, formats, imports, executable, reason, repo, package: pkg, version = VERSION } = {}) {
61
138
  assert([LEGACY_VERSION, VERSION].includes(version))
62
139
  assert(['node_modules', 'full'].includes(config.scope))
63
140
  this.version = version
@@ -68,15 +145,15 @@ export class Bundle {
68
145
  this.imports = imports ?? new Map()
69
146
  this.executable = executable ?? new Set()
70
147
  this.reason = reason
148
+ this.repo = normalizeRepo(repo)
149
+ this.package = pkg
71
150
  }
72
151
 
73
152
  // Flat project-relative view of the raw stored file contents (resources stay base64).
74
153
  get sources() {
75
154
  const m = new Map()
76
155
  for (const [dir, { files }] of this.modules) {
77
- for (const [rel, content] of Object.entries(files)) {
78
- m.set(moduleFileKey(dir, rel), content)
79
- }
156
+ for (const [rel, content] of Object.entries(files)) m.set(moduleFileKey(dir, rel), content)
80
157
  }
81
158
  return m
82
159
  }
@@ -96,22 +173,31 @@ export class Bundle {
96
173
  }
97
174
 
98
175
  static parse(text) {
99
- const json = JSON.parse(text)
100
- assert(json.version === VERSION || json.version === LEGACY_VERSION)
101
- assert(['node_modules', 'full'].includes(json.config?.scope))
102
- assert(isPlainObject(json.formats))
103
- assert(isPlainObject(json.imports))
176
+ return Bundle.fromJSON(JSON.parse(text))
177
+ }
104
178
 
105
- // Validate formats into a typed Map early: a raw-object lookup like `__proto__` would hit the prototype.
106
- const formats = new Map()
107
- for (const [file, format] of Object.entries(json.formats)) {
108
- assert(!posixPathEscapes(file))
109
- assert(KNOWN_FORMATS.has(format), `unknown format '${format}' for ${file}`)
110
- // '' and '.' alias to the same key (older bundles keyed the root listing ''); normalize, fail closed on dupes.
111
- const key = file === '' ? '.' : file
112
- assert(!formats.has(key), `duplicate format key '${key}'`)
113
- formats.set(key, format)
179
+ // The `sources` key of the file whose contents sit at JSON key path `path`, else undefined; throws if non-canonical.
180
+ static fileKeyAt(path) {
181
+ const [top, dir, files, rel] = path
182
+ if (typeof dir !== 'string') return undefined
183
+ // v0 `sources.<path>`
184
+ if (path.length === 2 && top === 'sources') {
185
+ const split = inferModuleDir(dir)
186
+ return canonicalFileKey(split.dir, split.rel, 'bundle')
114
187
  }
188
+ // v1 `sources|modules.<dir>.files.<rel>`
189
+ if (path.length === 4 && (top === 'sources' || top === 'modules') && files === 'files' && typeof rel === 'string') {
190
+ return canonicalFileKey(dir, rel, 'bundle')
191
+ }
192
+ return undefined
193
+ }
194
+
195
+ // parse() on an already-parsed value; `contents: false` takes a symbol placeholder per file and locks contents out.
196
+ static fromJSON(json, { contents = true } = {}) {
197
+ assert(json.version === VERSION || json.version === LEGACY_VERSION)
198
+ assert(['node_modules', 'full'].includes(json.config?.scope))
199
+ // Validated into a typed Map early: a raw-object lookup like `__proto__` would hit the prototype.
200
+ const formats = parseFormats(json.formats)
115
201
 
116
202
  const modules = new Map()
117
203
  let entries = new Set()
@@ -122,73 +208,44 @@ export class Bundle {
122
208
  assert(typeof json.modules === 'object' && json.modules !== null)
123
209
  for (const [dir, info] of Object.entries(json.modules)) {
124
210
  assert(hasNodeModulesSegment(dir))
125
- assert(!posixPathEscapes(dir))
211
+ assertArtifactPath(dir, 'bundle')
126
212
  assert(info?.name && info.version && info.files)
127
- modules.set(dir, normalize(info))
213
+ modules.set(dir, normalizeModule(info, dir, 'bundle'))
128
214
  }
129
215
  }
130
216
  if (full) {
131
217
  assert(json.sources && typeof json.sources === 'object')
132
218
  for (const [dir, info] of Object.entries(json.sources)) {
133
219
  assert(!hasNodeModulesSegment(dir))
134
- assert(!posixPathEscapes(dir))
135
- assert(info?.name && info.version && info.files)
136
- modules.set(dir, normalize(info))
220
+ assertArtifactPath(dir, 'bundle')
221
+ // A workspace bucket may omit version (a private/unpublished package.json can lack one).
222
+ assert(info?.name && info.files)
223
+ modules.set(dir, normalizeModule(info, dir, 'bundle'))
137
224
  }
138
225
  // Empty entries are valid (`stasis add` attests files without making them entry points); state.assertEntry fails closed on an empty set.
139
- assert(json.entries === undefined || Array.isArray(json.entries))
140
- entries = new Set(json.entries)
226
+ if (json.entries !== undefined) entries = parseEntries(json.entries, 'bundle')
141
227
  } else {
142
228
  assert(json.entries === undefined)
143
229
  assert(json.sources === undefined)
144
230
  }
145
- for (const [, { files }] of modules) {
146
- // posixPathEscapes (not a '..' prefix): also catches mid-path escapes and absolute paths.
147
- for (const rel of Object.keys(files)) assert(!posixPathEscapes(rel))
148
- }
149
231
  } else {
150
232
  assert(json.sources)
151
233
  for (const [path, content] of Object.entries(json.sources)) {
152
- assert(!posixPathEscapes(path))
234
+ assertArtifactPath(path, 'bundle')
153
235
  const { dir, rel, name } = inferModuleDir(path)
154
236
  assert(!posixPathEscapes(dir) && !posixPathEscapes(rel))
155
237
  if (!modules.has(dir)) modules.set(dir, { name, version: null, files: Object.create(null) })
156
- modules.get(dir).files[rel] = content
238
+ const { files } = modules.get(dir)
239
+ assert(!Object.hasOwn(files, rel), `bundle: duplicate file key '.' (v0 '' and '.')`)
240
+ files[rel] = content
157
241
  }
158
242
  }
159
243
 
160
244
  // Flat keys must be unique across buckets: two different bucket splits can flatten to one path, and the `sources` getter would serve either payload.
161
- const flatKeys = new Set()
162
- for (const [dir, { files }] of modules) {
163
- for (const rel of Object.keys(files)) {
164
- const key = moduleFileKey(dir, rel)
165
- assert(!flatKeys.has(key), `duplicate file key '${key}' across bundle buckets`)
166
- flatKeys.add(key)
167
- }
168
- }
245
+ const flatKeys = flatFileKeys(modules, 'bundle', duplicateKey)
246
+ const imports = parseImports(json.imports)
169
247
 
170
- // Reject paths escaping the root here (incl. mid-path `a/../../x`): getImport resolves against the root at load.
171
- const imports = objectToMaps(json.imports)
172
- const assertTarget = (target) => {
173
- if (typeof target === 'string') {
174
- assert(!posixPathEscapes(target))
175
- return
176
- }
177
- assert(target instanceof Map && target.size > 0, 'import target must be a file or a non-empty {platform: file} map')
178
- for (const [platform, file] of target) {
179
- assert(typeof platform === 'string' && platform.length > 0 && !platform.includes('/'), `invalid platform key '${platform}'`)
180
- assert(typeof file === 'string')
181
- assert(!posixPathEscapes(file))
182
- }
183
- }
184
- for (const [, byParent] of imports) {
185
- assert(byParent instanceof Map)
186
- for (const [parent, specifiers] of byParent) {
187
- assert(!posixPathEscapes(parent))
188
- assert(specifiers instanceof Map)
189
- for (const [, target] of specifiers) assertTarget(target)
190
- }
191
- }
248
+ if (!contents) for (const [dir, info] of modules) modules.set(dir, lockModule(dir, info))
192
249
 
193
250
  return new Bundle({
194
251
  version: json.version,
@@ -202,54 +259,39 @@ export class Bundle {
202
259
  ? parseExecutable(json.executable, { what: 'bundle', files: flatKeys, formats, scope: json.config.scope })
203
260
  : new Set(),
204
261
  reason: isPlainObject(json.reason) ? json.reason : undefined,
262
+ repo: parsedRepo(json.repo),
263
+ package: json.package,
205
264
  })
206
265
  }
207
266
 
208
- #groupedFromModules() {
209
- const moduleEntries = []
210
- const sourceEntries = []
211
- for (const [dir, { name, version, ecosystem, files }] of this.modules) {
212
- if (Object.keys(files).length === 0) continue
213
- const inNodeModules = hasNodeModulesSegment(dir)
214
- if (inNodeModules) assert(name && version && files)
215
- const sorted = fromEntries(Object.entries(files).toSorted((a, b) => sortPaths(a[0], b[0])))
216
- const target = inNodeModules ? moduleEntries : sourceEntries
217
- target.push([dir, { name, version, ...(ecosystem === undefined ? {} : { ecosystem }), files: sorted }])
218
- }
219
- moduleEntries.sort((a, b) => sortPaths(a[0], b[0]))
220
- sourceEntries.sort((a, b) => sortPaths(a[0], b[0]))
221
- return { modules: fromEntries(moduleEntries), sources: fromEntries(sourceEntries) }
222
- }
223
-
224
267
  serialize() {
225
- const entries = fileSetToObject(this.entries)
226
- const { modules, sources } = this.#groupedFromModules()
227
- const formats = fileMapToObject(this.formats)
228
- const imports = fileMapToObject(this.imports)
268
+ // Never write an artifact that parse would reject.
269
+ flatFileKeys(this.modules, 'bundle', duplicateKey)
270
+ const { modules, sources } = groupModules(this.modules, { skipEmpty: true, what: 'bundle' })
271
+ const full = this.config.scope === 'full'
229
272
  const data = { version: VERSION, config: this.config }
230
- if (this.config.scope === 'full') Object.assign(data, { entries, sources })
231
- Object.assign(data, { modules, formats, imports })
273
+ if (this.repo !== undefined) data.repo = this.repo
274
+ if (this.package !== undefined) data.package = this.package
275
+ if (full) data.entries = serializeEntries(this.entries, 'bundle')
276
+ data.formats = serializeFormats(this.formats)
277
+ data.imports = serializeImports(this.imports)
232
278
  const executable = serializeExecutable(this.executable, {
233
279
  what: 'bundle', modules: this.modules, formats: this.formats, scope: this.config.scope,
234
280
  })
235
281
  if (executable !== undefined) data.executable = executable
236
- if (this.reason !== undefined) data.reason = this.reason
282
+ // Canonicalized like every other sorted field, so a parsed artifact's order can't leak into the bytes.
283
+ if (this.reason !== undefined) data.reason = mergeReason(this.reason, undefined)
284
+ // File contents are written last, after every other key: sources, then modules.
285
+ if (full) data.sources = sources
286
+ data.modules = modules
237
287
  return JSON.stringify(data, undefined, 2)
238
288
  }
239
289
 
240
290
  // Stamp `consumer` onto every carried file in the informational `reason` map.
241
291
  withReason(consumer) {
242
- const files = [...this.sources.keys()]
243
- return new Bundle({
244
- version: this.version,
245
- config: this.config,
246
- entries: this.entries,
247
- modules: this.modules,
248
- formats: this.formats,
249
- imports: this.imports,
250
- executable: this.executable,
251
- reason: mergeReason(this.reason, { [consumer]: files }),
252
- })
292
+ const { version, config, entries, modules, formats, imports, executable, repo, package: pkg } = this
293
+ const reason = mergeReason(this.reason, { [consumer]: [...this.sources.keys()] })
294
+ return new Bundle({ version, config, entries, modules, formats, imports, executable, reason, repo, package: pkg })
253
295
  }
254
296
 
255
297
  // Strict union of two Bundles (returns a NEW one): any genuine conflict throws -- a bundle is an attestation.
@@ -265,6 +307,8 @@ export class Bundle {
265
307
  // `other` (the incoming, newer build) wins for the files it carries -- see mergeExecutableSets.
266
308
  executable: mergeExecutableSets(this.executable, other.executable, other.modules, this.config.scope),
267
309
  reason: mergeReason(this.reason, other.reason),
310
+ repo: mergeRepo(this.repo, other.repo),
311
+ package: mergePackage(this.package, other.package),
268
312
  })
269
313
  }
270
314
  }