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

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/host.js ADDED
@@ -0,0 +1,45 @@
1
+ import * as fs from 'node:fs'
2
+ import { createRequire, findPackageJSON } from 'node:module'
3
+ import { pathToFileURL } from 'node:url'
4
+
5
+ // Snapshotted before `stasis run --fs` patches node:fs, whose realpathSync doesn't throw ENOENT and
6
+ // whose statSync answers with synthetic modes.
7
+ const { lstatSync, opendirSync, readFileSync, readdirSync, readlinkSync, realpathSync, statSync } = fs
8
+
9
+ export const byName = (a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0)
10
+
11
+ let lastParent
12
+ let lastRequire
13
+
14
+ export const diskHost = {
15
+ stat(p) {
16
+ try {
17
+ return statSync(p, { throwIfNoEntry: false }) ?? null
18
+ } catch {
19
+ return null
20
+ }
21
+ },
22
+ readFile: (p) => readFileSync(p),
23
+ readdir: (p) => readdirSync(p, { withFileTypes: true }).toSorted(byName),
24
+ // In the filesystem's own order (readdirSync sorts; opendir doesn't).
25
+ readdirUnsorted(p) {
26
+ const entries = []
27
+ const handle = opendirSync(p)
28
+ try {
29
+ for (let e = handle.readSync(); e !== null; e = handle.readSync()) entries.push(e)
30
+ } finally {
31
+ handle.closeSync()
32
+ }
33
+ return entries
34
+ },
35
+ readlink: (p) => (lstatSync(p).isSymbolicLink() ? readlinkSync(p) : null),
36
+ realpath: (p) => realpathSync(p),
37
+ findPackageJSON: (p) => findPackageJSON(pathToFileURL(p).href),
38
+ resolve(parentFile, specifier, conditions) {
39
+ if (parentFile !== lastParent) {
40
+ lastRequire = createRequire(parentFile)
41
+ lastParent = parentFile
42
+ }
43
+ return lastRequire.resolve(specifier, { conditions })
44
+ },
45
+ }
package/src/loader.js CHANGED
@@ -1,6 +1,4 @@
1
- // stasis-core's run-time loader entry. Evaluating it -- `stasis-core run`, or
2
- // `node --import @exodus/stasis-core/loader` -- snapshots the lib's
3
- // node:fs/path/etc. bindings and registers the module hooks.
1
+ // Run-time loader entry (`node --import @exodus/stasis-core/loader`): evaluating it snapshots the lib's node:fs/path bindings before any patch.
4
2
  import { install } from './hooks.js'
5
3
 
6
4
  install()
package/src/lockfile.js CHANGED
@@ -1,13 +1,11 @@
1
- import { KNOWN_FORMATS, assert, fileMapToObject, fileSetToObject, fromEntries, isPlainObject, posixPathEscapes, sortPaths } from './util.js'
1
+ import { assert, assertArtifactPath, duplicateKeyError, serializeExecutable, flatFileKeys, groupModules, hasNodeModulesSegment, mergeExecutableSets, mergeFormatMaps, mergeImportMaps, mergeModuleMaps, normalizeModule, parseEntries, parseExecutable, parseFormats, parseImports, serializeEntries, serializeFormats, serializeImports } from './artifact-util.js'
2
2
 
3
3
  const VERSION = 0
4
4
 
5
- const normalize = ({ name, version, ecosystem, files }) => {
6
- // `ecosystem` (when present) names the package ecosystem a dependency came from
7
- // (`npm`, `composer`, `soldeer`); the workspace/top-level buckets omit it.
8
- assert(ecosystem === undefined || typeof ecosystem === 'string')
9
- return { name, version, ...(ecosystem === undefined ? {} : { ecosystem }), files: fromEntries(Object.entries(files)) }
10
- }
5
+ const duplicateKey = duplicateKeyError('lockfile', 'lockfile (lock=replace)')
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
11
9
 
12
10
  export class Lockfile {
13
11
  static VERSION = VERSION
@@ -16,30 +14,28 @@ export class Lockfile {
16
14
  config
17
15
  entries
18
16
  modules
19
- // Recorded resolutions, mirroring the bundle's `imports` shape:
20
- // conditions key -> parent file -> specifier -> resolved file. `null` (not an
21
- // empty Map) when the lockfile predates resolution attestation -- consumers
22
- // use that to tell "attests no resolutions" apart from "doesn't attest them".
17
+ // conditions -> parent -> specifier -> resolved file. A Map from parse; null only on in-memory constructs that don't attest it.
23
18
  imports
24
- // Recorded loader formats: project-relative file -> Node format string
25
- // (module/commonjs/json/{module,commonjs}-typescript), mirroring the bundle's
26
- // `formats` map. `null` when the lockfile predates format attestation, same
27
- // "attests none" vs "doesn't attest" distinction as `imports`.
19
+ // file -> format string. Same Map/null rule as imports.
28
20
  formats
21
+ // Project-relative paths of attested files carrying a POSIX execute bit, for `stasis extract`. Files only, never a `directory`.
22
+ executable
29
23
 
30
- constructor({ config = { scope: 'full' }, entries, modules, imports, formats } = {}) {
24
+ constructor({ config = { scope: 'full' }, entries, modules, imports, formats, executable } = {}) {
31
25
  assert(['node_modules', 'full'].includes(config.scope))
32
26
  this.config = config
33
27
  this.entries = entries ?? new Set()
34
28
  this.modules = modules ?? new Map()
35
29
  this.imports = imports ?? null
36
30
  this.formats = formats ?? null
31
+ this.executable = executable ?? new Set()
37
32
  }
38
33
 
39
34
  static parse(text) {
40
35
  const json = JSON.parse(text)
41
36
  assert(json.version === VERSION)
42
37
  assert(['node_modules', 'full'].includes(json.config?.scope))
38
+ assert(json.imports !== undefined && json.formats !== undefined, 'lockfile must attest imports and formats')
43
39
 
44
40
  const full = json.config.scope === 'full'
45
41
  assert(!!json.entries === full)
@@ -48,105 +44,79 @@ export class Lockfile {
48
44
 
49
45
  const modules = new Map()
50
46
  for (const [dir, info] of Object.entries(json.modules)) {
51
- assert(dir.includes('node_modules'))
47
+ assert(hasNodeModulesSegment(dir))
52
48
  assert(info?.name && info.version && info.files)
53
- modules.set(dir, normalize(info))
49
+ modules.set(dir, normalizeModule(lockRecord(info), dir, 'lockfile'))
54
50
  }
55
51
 
56
52
  let entries = new Set()
57
53
  if (full) {
58
- assert(Array.isArray(json.entries))
59
- entries = new Set(json.entries)
54
+ entries = parseEntries(json.entries, 'lockfile')
60
55
  for (const [dir, info] of Object.entries(json.sources)) {
61
- assert(!dir.includes('node_modules'))
62
- modules.set(dir, normalize(info))
56
+ assert(!hasNodeModulesSegment(dir))
57
+ // A workspace bucket may omit version (a private/unpublished package.json can lack one).
58
+ assert(info?.name && info.files)
59
+ modules.set(dir, normalizeModule(lockRecord(info), dir, 'lockfile'))
63
60
  }
64
61
  }
65
62
 
63
+ // Flat keys must be unique across buckets (mirrors Bundle.parse): two bucket splits can flatten
64
+ // to one path, and hashes/attestation lookups key on the flat path.
66
65
  for (const [dir, { files }] of modules) {
67
- assert(!posixPathEscapes(dir))
66
+ assertArtifactPath(dir, 'lockfile')
68
67
  assert(files)
69
- for (const name of Object.keys(files)) {
70
- assert(!posixPathEscapes(name))
71
- }
72
68
  }
69
+ const flatKeys = flatFileKeys(modules, 'lockfile', duplicateKey)
73
70
 
74
- let imports = null
75
- if (json.imports !== undefined) {
76
- assert(isPlainObject(json.imports))
77
- imports = new Map()
78
- for (const [conditions, byParent] of Object.entries(json.imports)) {
79
- assert(isPlainObject(byParent))
80
- const parents = new Map()
81
- for (const [parent, specifiers] of Object.entries(byParent)) {
82
- assert(!posixPathEscapes(parent))
83
- assert(isPlainObject(specifiers))
84
- const specs = new Map()
85
- for (const [specifier, target] of Object.entries(specifiers)) {
86
- // A file string (the common case) or, for a `--metro` multi-platform
87
- // lockfile, a { platform: file } map for an edge that resolves
88
- // differently per platform. Reject any other shape (fail closed).
89
- if (typeof target === 'string') {
90
- assert(!posixPathEscapes(target))
91
- specs.set(specifier, target)
92
- } else {
93
- assert(isPlainObject(target) && Object.keys(target).length > 0,
94
- 'import target must be a file or a non-empty {platform: file} map')
95
- const byPlatform = new Map()
96
- for (const [platform, file] of Object.entries(target)) {
97
- assert(typeof platform === 'string' && platform.length > 0 && !platform.includes('/'), `invalid platform key '${platform}'`)
98
- assert(typeof file === 'string')
99
- assert(!posixPathEscapes(file))
100
- byPlatform.set(platform, file)
101
- }
102
- specs.set(specifier, byPlatform)
103
- }
104
- }
105
- parents.set(parent, specs)
106
- }
107
- imports.set(conditions, parents)
108
- }
109
- }
110
-
111
- let formats = null
112
- if (json.formats !== undefined) {
113
- assert(isPlainObject(json.formats))
114
- formats = new Map()
115
- for (const [file, format] of Object.entries(json.formats)) {
116
- assert(!posixPathEscapes(file))
117
- // KNOWN_FORMATS is stasis-core's full universe of recognized formats.
118
- // Rejecting unknowns here -- not at a downstream branch -- means a
119
- // tampered or forward-incompatible lockfile fails closed at the schema
120
- // boundary, with a message that names the offending value.
121
- assert(KNOWN_FORMATS.has(format), `unknown format '${format}' for ${file}`)
122
- formats.set(file, format)
123
- }
124
- }
71
+ const imports = parseImports(json.imports)
72
+ const formats = parseFormats(json.formats)
73
+ // Every executable must be a file this lockfile attests.
74
+ const executable = json.executable === undefined
75
+ ? new Set()
76
+ : parseExecutable(json.executable, { what: 'lockfile', files: flatKeys, formats, scope: json.config.scope })
125
77
 
126
- return new Lockfile({ config: json.config, entries, modules, imports, formats })
78
+ return new Lockfile({ config: json.config, entries, modules, imports, formats, executable })
127
79
  }
128
80
 
129
81
  serialize() {
130
- const entries = fileSetToObject(this.entries)
131
- const modules = []
132
- const sources = []
133
- for (const [dir, { name, version, ecosystem, files }] of this.modules) {
134
- const inNodeModules = dir.includes('node_modules')
135
- if (inNodeModules) assert(name && version && files)
136
- const type = inNodeModules ? modules : sources
137
- const sorted = fromEntries(Object.entries(files).toSorted((a, b) => sortPaths(a[0], b[0])))
138
- type.push([dir, { name, version, ...(ecosystem === undefined ? {} : { ecosystem }), files: sorted }])
139
- }
140
- modules.sort((a, b) => sortPaths(a[0], b[0]))
141
- sources.sort((a, b) => sortPaths(a[0], b[0]))
142
-
82
+ // Never write an artifact that parse would reject.
83
+ flatFileKeys(this.modules, 'lockfile', duplicateKey)
84
+ const { modules, sources } = groupModules(this.modules, { metadata: false, what: 'lockfile' })
143
85
  const store = { version: this.version, config: this.config }
144
- if (this.config.scope === 'full') Object.assign(store, { entries, sources: fromEntries(sources) })
145
- Object.assign(store, { modules: fromEntries(modules) })
146
- // Legacy lockfiles (imports/formats === null) round-trip without the key,
147
- // so parse-serialize of an old file stays byte-stable.
148
- if (this.imports !== null) Object.assign(store, { imports: fileMapToObject(this.imports) })
149
- if (this.formats !== null) Object.assign(store, { formats: fileMapToObject(this.formats) })
86
+ if (this.config.scope === 'full') Object.assign(store, { entries: serializeEntries(this.entries, 'lockfile'), sources })
87
+ store.modules = modules
88
+ if (this.imports !== null) store.imports = serializeImports(this.imports)
89
+ if (this.formats !== null) store.formats = serializeFormats(this.formats)
90
+ const executable = serializeExecutable(this.executable, {
91
+ what: 'lockfile',
92
+ modules: this.modules,
93
+ // Null on an in-memory construct; an unrecorded format is simply not a directory/stat.
94
+ formats: this.formats ?? new Map(),
95
+ scope: this.config.scope,
96
+ })
97
+ if (executable !== undefined) store.executable = executable
150
98
  return JSON.stringify(store, undefined, 2) + '\n'
151
99
  }
100
+
101
+ // Strict union of two Lockfiles (returns a NEW one): buckets must agree, and a file in both must carry the identical hash (fail closed).
102
+ merge(other) {
103
+ assert(this.config.scope === other.config.scope,
104
+ `lockfile merge: scope mismatch ('${this.config.scope}' vs '${other.config.scope}')`)
105
+ return new Lockfile({
106
+ config: { scope: this.config.scope },
107
+ entries: new Set([...this.entries, ...other.entries]),
108
+ modules: mergeModuleMaps(this.modules, other.modules, 'lockfile merge'),
109
+ imports: mergeNullable(this.imports, other.imports, (a, b) => mergeImportMaps(a, b, 'lockfile merge'), 'imports'),
110
+ formats: mergeNullable(this.formats, other.formats, (a, b) => mergeFormatMaps(a, b, 'lockfile merge'), 'formats'),
111
+ // `other` (the incoming, newer lockfile) wins for the files it records -- see mergeExecutableSets.
112
+ executable: mergeExecutableSets(this.executable, other.executable, other.modules, this.config.scope),
113
+ })
114
+ }
115
+ }
116
+
117
+ const mergeNullable = (a, b, merge, what) => {
118
+ if (a === null && b === null) return null
119
+ assert(a !== null && b !== null,
120
+ `lockfile merge: cannot merge ${what} (one lockfile attests ${what}, the other does not)`)
121
+ return merge(a, b)
152
122
  }