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

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