@exodus/stasis-core 1.0.0-beta.8 → 1.0.0-rc.0

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 CHANGED
@@ -1,10 +1,11 @@
1
1
  import * as fs from 'node:fs'
2
2
  import { createRequire, findPackageJSON } from 'node:module'
3
+ import { join, matchesGlob, relative } from 'node:path'
3
4
  import { pathToFileURL } from 'node:url'
4
5
 
5
6
  // Snapshotted before `stasis run --fs` patches node:fs, whose realpathSync doesn't throw ENOENT and
6
7
  // whose statSync answers with synthetic modes.
7
- const { lstatSync, opendirSync, readFileSync, readdirSync, readlinkSync, realpathSync, statSync } = fs
8
+ const { globSync, lstatSync, opendirSync, readFileSync, readdirSync, readlinkSync, realpathSync, statSync } = fs
8
9
 
9
10
  export const byName = (a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0)
10
11
 
@@ -34,6 +35,13 @@ export const diskHost = {
34
35
  },
35
36
  readlink: (p) => (lstatSync(p).isSymbolicLink() ? readlinkSync(p) : null),
36
37
  realpath: (p) => realpathSync(p),
38
+ // `exclude` takes an absolute path, so that walk is over Dirents: else Node hands it a bare file name.
39
+ glob(pattern, { cwd, exclude } = {}) {
40
+ if (exclude === undefined) return globSync(pattern, { cwd })
41
+ const pathOf = (dirent) => join(dirent.parentPath, dirent.name)
42
+ return globSync(pattern, { cwd, withFileTypes: true, exclude: (dirent) => exclude(pathOf(dirent)) }).map((dirent) => relative(cwd, pathOf(dirent)))
43
+ },
44
+ matchesGlob,
37
45
  findPackageJSON: (p) => findPackageJSON(pathToFileURL(p).href),
38
46
  resolve(parentFile, specifier, conditions) {
39
47
  if (parentFile !== lastParent) {
package/src/loader.js CHANGED
@@ -1,4 +1,4 @@
1
- // Run-time loader entry (`node --import @exodus/stasis-core/loader`): evaluating it snapshots the lib's node:fs/path bindings before any patch.
1
+ // `node --import @exodus/stasis-core/loader`: evaluating it snapshots the lib's node:fs bindings before any patch.
2
2
  import { install } from './hooks.js'
3
3
 
4
4
  install()
package/src/lockfile.js CHANGED
@@ -1,122 +1,106 @@
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'
1
+ import { assert, assertScope, duplicateKeyError, flatFileKeys, isPlainObject, mergeExecutableSets, mergeFormatMaps, mergeImportMaps, mergeModuleMaps, moduleFileKey, moduleFileKeys, moduleInfo, normalizeRepo, parseBuckets, parseEntries, parseExecutable, parseFormats, parseImports, serializedParts } from './artifact-util.js'
2
2
 
3
3
  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`, metadata a bundle carries and nothing attests.
8
- const lockRecord = ({ repo: _metadata, ...info }) => info
7
+ // What the tarball and patch a package was installed from are, and the copies it ships, so a lockfile can be audited alone.
8
+ const LOCK_METADATA = ['integrity', 'patch', 'vendored']
9
9
 
10
10
  export class Lockfile {
11
11
  static VERSION = VERSION
12
12
 
13
13
  version = VERSION
14
- config
15
- entries
16
- modules
17
- // conditions -> parent -> specifier -> resolved file. A Map from parse; null only on in-memory constructs that don't attest it.
18
- imports
19
- // file -> format string. Same Map/null rule as imports.
20
- formats
21
- // Project-relative paths of attested files carrying a POSIX execute bit, for `stasis extract`. Files only, never a `directory`.
22
- executable
23
14
 
24
- constructor({ config = { scope: 'full' }, entries, modules, imports, formats, executable } = {}) {
25
- assert(['node_modules', 'full'].includes(config.scope))
15
+ // Where a GitHub build's (`stasis github-bundle`'s) was built, as a bundle's `repo`; validated on every
16
+ // assignment, and frozen. Only github-bundle writes one, and holds a build to it; `stasis validate` reads own code
17
+ // of it. Neither `stasis bundle` nor `stasis run` reads one: a merge, or a lockfile of a bundle, carries none.
18
+ #repo
19
+ get repo() {
20
+ return this.#repo
21
+ }
22
+ set repo(repo) {
23
+ this.#repo = normalizeRepo(repo, 'lockfile repo')
24
+ }
25
+
26
+ constructor({ config = { scope: 'full' }, entries, modules, imports, formats, executable, repo } = {}) {
27
+ assertScope(config.scope, 'lockfile')
26
28
  this.config = config
29
+ this.repo = repo
27
30
  this.entries = entries ?? new Set()
28
31
  this.modules = modules ?? new Map()
32
+ // conditions -> parent -> specifier -> resolved file, and file -> format: null only on an in-memory construct.
29
33
  this.imports = imports ?? null
30
34
  this.formats = formats ?? null
31
- this.executable = executable ?? new Set()
35
+ this.executable = executable ?? new Set() // files only, never a `directory`
36
+ }
37
+
38
+ // Imports and formats carry across, else a frozen run would skip those cross-checks.
39
+ static fromBundle(bundle, integrityOf) {
40
+ const modules = new Map()
41
+ for (const [dir, m] of bundle.modules) {
42
+ const files = Object.create(null)
43
+ for (const [rel, content] of Object.entries(m.files)) files[rel] = integrityOf(moduleFileKey(dir, rel), content)
44
+ modules.set(dir, moduleInfo({ ...m, files }))
45
+ }
46
+ return new Lockfile({ config: bundle.config, entries: bundle.entries, modules, imports: bundle.imports, formats: bundle.formats, executable: bundle.executable })
32
47
  }
33
48
 
34
49
  static parse(text) {
35
50
  const json = JSON.parse(text)
36
51
  assert(json.version === VERSION)
37
- assert(['node_modules', 'full'].includes(json.config?.scope))
52
+ assertScope(json.config?.scope, 'lockfile')
38
53
  assert(json.imports !== undefined && json.formats !== undefined, 'lockfile must attest imports and formats')
39
-
40
54
  const full = json.config.scope === 'full'
41
55
  assert(!!json.entries === full)
42
56
  assert(!!json.sources === full)
43
- assert(json.modules)
44
-
45
- const modules = new Map()
46
- for (const [dir, info] of Object.entries(json.modules)) {
47
- assert(hasNodeModulesSegment(dir))
48
- assert(info?.name && info.version && info.files)
49
- modules.set(dir, normalizeModule(lockRecord(info), dir, 'lockfile'))
50
- }
51
-
52
- let entries = new Set()
53
- if (full) {
54
- entries = parseEntries(json.entries, 'lockfile')
55
- for (const [dir, info] of Object.entries(json.sources)) {
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'))
60
- }
61
- }
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.
65
- for (const [dir, { files }] of modules) {
66
- assertArtifactPath(dir, 'lockfile')
67
- assert(files)
68
- }
57
+ assert(isPlainObject(json.modules), 'lockfile: modules must be an object')
58
+ const entries = full ? parseEntries(json.entries, 'lockfile') : new Set()
59
+ const modules = parseBuckets(json, 'lockfile', LOCK_METADATA)
60
+ // Unique across buckets, as in Bundle.parse: hashes and attestation lookups key on the flat path.
69
61
  const flatKeys = flatFileKeys(modules, 'lockfile', duplicateKey)
70
-
71
62
  const imports = parseImports(json.imports)
72
63
  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 })
77
-
78
- return new Lockfile({ config: json.config, entries, modules, imports, formats, executable })
64
+ const executable = parseExecutable(json.executable, { what: 'lockfile', files: flatKeys, formats, scope: json.config.scope })
65
+ return new Lockfile({ config: json.config, entries, modules, imports, formats, executable, repo: json.repo })
79
66
  }
80
67
 
81
68
  serialize() {
82
- // Never write an artifact that parse would reject.
83
69
  flatFileKeys(this.modules, 'lockfile', duplicateKey)
84
- const { modules, sources } = groupModules(this.modules, { repo: false, what: 'lockfile' })
85
- const store = { version: this.version, config: this.config }
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
70
+ const { entries, sources, modules, imports, formats, executable } = serializedParts(this, 'lockfile', { metadata: LOCK_METADATA })
71
+ const store = { version: this.version, config: this.config, repo: this.repo, entries, sources, modules, imports, formats, executable }
98
72
  return JSON.stringify(store, undefined, 2) + '\n'
99
73
  }
100
74
 
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) {
75
+ // A strict union: buckets must agree, and a file in both must carry the identical hash (fail closed).
76
+ merge(other, label = 'lockfile merge', options) {
103
77
  assert(this.config.scope === other.config.scope,
104
- `lockfile merge: scope mismatch ('${this.config.scope}' vs '${other.config.scope}')`)
78
+ `${label}: scope mismatch ('${this.config.scope}' vs '${other.config.scope}')`)
105
79
  return new Lockfile({
106
80
  config: { scope: this.config.scope },
107
81
  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'),
82
+ modules: mergeModuleMaps(this.modules, other.modules, label, options),
83
+ imports: mergeNullable(this.imports, other.imports, mergeImportMaps, 'imports', label),
84
+ formats: mergeNullable(this.formats, other.formats, mergeFormatMaps, 'formats', label),
111
85
  // `other` (the incoming, newer lockfile) wins for the files it records -- see mergeExecutableSets.
112
86
  executable: mergeExecutableSets(this.executable, other.executable, other.modules, this.config.scope),
113
87
  })
114
88
  }
89
+
90
+ // merge, refusing a file both record whose execute bit `other` gives otherwise (merge lets `other`'s win).
91
+ mergeAgreeing(other, label = 'lockfile merge', options) {
92
+ const merged = this.merge(other, label, options)
93
+ const recorded = moduleFileKeys(this.modules, { scope: this.config.scope })
94
+ for (const file of moduleFileKeys(other.modules, { scope: other.config.scope })) {
95
+ if (recorded.has(file) && this.executable.has(file) !== other.executable.has(file)) throw new Error(`${label}: ${file}'s execute bit differs`)
96
+ }
97
+ return merged
98
+ }
115
99
  }
116
100
 
117
- const mergeNullable = (a, b, merge, what) => {
101
+ const mergeNullable = (a, b, merge, what, label) => {
118
102
  if (a === null && b === null) return null
119
103
  assert(a !== null && b !== null,
120
- `lockfile merge: cannot merge ${what} (one lockfile attests ${what}, the other does not)`)
121
- return merge(a, b)
104
+ `${label}: cannot merge ${what} (one lockfile attests ${what}, the other does not)`)
105
+ return merge(a, b, label)
122
106
  }
package/src/policy.js ADDED
@@ -0,0 +1,222 @@
1
+ import { posix, relative, resolve } from 'node:path'
2
+
3
+ import { dependencyEcosystem, hasNodeModulesSegment, moduleFileKeys, posixPathEscapes, sortedByPath, splitNodeModulesPath } from './artifact-util.js'
4
+ import { readPackageJson } from './bundle-util.js'
5
+ import { diskHost } from './host.js'
6
+ import { memoized, relativeEscapes, toPosix } from './util.js'
7
+
8
+ // Each rule is checked on its own, and an artifact meets every Policy that applies: none overrides another.
9
+ export const POLICY_KEYS = ['allowedPaths', 'disallowedPaths', 'allowedModules', 'disallowedModules']
10
+ const PATH_KEYS = new Set(['allowedPaths', 'disallowedPaths'])
11
+ const ALLOWING = new Set(['allowedPaths', 'allowedModules'])
12
+
13
+ const MAX_ALTERNATIVES = 256
14
+ const MAX_LISTED = 20
15
+
16
+ // The patterns every glob reads alike; anything else (a class, an escape, an extglob, a range, a lone or nested
17
+ // brace) is refused, as Node's glob (`extra`'s) may read it otherwise.
18
+ const SIMPLE = /^(?:[\p{L}\p{N}_.@+\-/*?]|\{[\p{L}\p{N}_.@+\-/*?]*,[\p{L}\p{N}_.@+\-/*?,]*\})*$/u
19
+ const isSimple = (pattern) => SIMPLE.test(pattern) && !/[^/]\*\*|\*\*[^/]/u.test(pattern)
20
+
21
+ // As a shell expands brace lists, but for an empty alternative, which Node's glob drops (`{src,}` is `src` alone).
22
+ function alternativesOf(label, pattern) {
23
+ if (!isSimple(pattern)) {
24
+ throw new Error(`${label}: ${JSON.stringify(pattern)} is not supported: a pattern is names of letters, digits ` +
25
+ 'and `_.@+-`, with `*`, `?`, `**` as a whole name and `{a,b}` lists (none nested); match any other character with `?`')
26
+ }
27
+ let out = ['']
28
+ for (const [, text, list] of pattern.matchAll(/([^{]*)(?:\{([^}]*)\})?/gu)) {
29
+ out = out.flatMap((head) => (list === undefined ? [head + text] : list.split(',').map((item) => head + text + item)))
30
+ if (out.length > MAX_ALTERNATIVES) throw new Error(`${label}: ${JSON.stringify(pattern)} expands to more than ${MAX_ALTERNATIVES} patterns`)
31
+ }
32
+ out = out.filter((alternative) => alternative !== '')
33
+ if (out.length === 0) throw new Error(`${label}: ${JSON.stringify(pattern)} expands to no pattern`)
34
+ return out
35
+ }
36
+
37
+ const escapeRegExp = (text) => text.replaceAll(/[$()*+.?[\\\]^{|}]/gu, '\\$&')
38
+
39
+ // `*` and `?` match a dotfile's characters too, so `.env` doesn't slip past `**`.
40
+ const segmentSource = (segment) => segment.replaceAll(/[*?]|[^*?]+/gu, (part) => (part === '*' ? '[^/]*' : part === '?' ? '[^/]' : escapeRegExp(part)))
41
+
42
+ // A `**` segment is any number of segments, none included (`a/**` matches `a`, `**/b` matches `b`).
43
+ function patternSource(pattern) {
44
+ const segments = pattern.split('/').filter((segment, i, all) => !(segment === '**' && all[i - 1] === '**'))
45
+ let out = ''
46
+ for (const [i, segment] of segments.entries()) {
47
+ const first = i === 0
48
+ const last = i === segments.length - 1
49
+ if (segment === '**') {
50
+ out += first && last ? '.*' : first ? '(?:.*/)?' : last ? '(?:/.*)?' : '/(?:.*/)?'
51
+ } else {
52
+ if (!first && segments[i - 1] !== '**') out += '/'
53
+ out += segmentSource(segment)
54
+ }
55
+ }
56
+ return out
57
+ }
58
+
59
+ // `s`: a name may hold a line break, which `.*` (`**`, a directory's paths) must match too.
60
+ const compile = (alternatives, suffix = '') => new RegExp(`^(?:${alternatives.map(patternSource).join('|')})${suffix}$`, 'su')
61
+
62
+ // `src` takes in src/**; the root's own `--fs` listing (`.`) is matched by `.` and `**` alone.
63
+ function pathPattern(label, pattern) {
64
+ const alternatives = alternativesOf(label, pattern).map((alternative) => posix.normalize(alternative).replace(/(?<=.)\/+$/u, ''))
65
+ if (alternatives.some(posixPathEscapes)) {
66
+ throw new Error(`${label}: ${JSON.stringify(pattern)} must be a path or pattern within the directory of stasis.config.json`)
67
+ }
68
+ if (alternatives.includes('.')) return { pattern, test: () => true }
69
+ const regex = compile(alternatives, '(?:/.*)?')
70
+ const matchesRoot = alternatives.some((alternative) => alternative.split('/').every((segment) => segment === '**'))
71
+ return { pattern, test: (path) => (path === '.' ? matchesRoot : regex.test(path)) }
72
+ }
73
+
74
+ // A path such as node_modules/left-pad would match no name, and so silently refuse nothing.
75
+ function modulePattern(label, pattern) {
76
+ const alternatives = alternativesOf(label, pattern)
77
+ const named = (alternative) => {
78
+ const segments = alternative.split('/')
79
+ return segments.length <= 2 && segments.every((segment) => segment !== '' && segment !== '.' && segment !== '..' && segment !== 'node_modules')
80
+ }
81
+ if (!alternatives.every(named)) throw new Error(`${label}: ${JSON.stringify(pattern)} is no package name or pattern of names (such as "left-pad", "@babel/*")`)
82
+ const regex = compile(alternatives)
83
+ return { pattern, test: (name) => name === pattern || regex.test(name) }
84
+ }
85
+
86
+ const listed = (items) => {
87
+ const shown = items.slice(0, MAX_LISTED).join(', ')
88
+ return items.length > MAX_LISTED ? `${shown}, and ${items.length - MAX_LISTED} more` : shown
89
+ }
90
+
91
+ const installedName = (dir) => splitNodeModulesPath(`${dir}/package.json`)?.name
92
+
93
+ const packageText = ({ dir, name, version, via }) => {
94
+ const installed = installedName(dir)
95
+ return `${name}${version === undefined ? '' : `@${version}`} at ${dir}` +
96
+ `${installed === undefined || installed === name ? '' : ` (installed as ${installed})`}${via === undefined ? '' : ` (linked from ${via})`}`
97
+ }
98
+
99
+ export const recordedIn = (path) => ` -- recorded in ${path} already`
100
+
101
+ // The lookup gives { real, pkg } for a path linking to another file in the root, `pkg` the dependency that one is in.
102
+ export function linksOn(root, host = diskHost) {
103
+ let realRoot
104
+ try {
105
+ realRoot = host.realpath(root)
106
+ } catch {
107
+ return () => undefined
108
+ }
109
+ const manifestOf = memoized((dir) => {
110
+ const manifest = readPackageJson(realRoot, `${dir}/package.json`, { host })
111
+ const name = typeof manifest?.name === 'string' && manifest.name !== '' ? manifest.name : installedName(dir)
112
+ return { dir, name, version: typeof manifest?.version === 'string' ? manifest.version : undefined }
113
+ })
114
+ return memoized((path) => {
115
+ const absolute = resolve(root, path)
116
+ let real
117
+ try {
118
+ real = host.realpath(absolute)
119
+ } catch {
120
+ return undefined // gone: a file a loaded artifact records
121
+ }
122
+ if (real === absolute) return undefined
123
+ const rel = toPosix(relative(realRoot, real)) || '.'
124
+ if (rel === path || relativeEscapes(rel)) return undefined
125
+ const dir = splitNodeModulesPath(rel)?.dir
126
+ const pkg = dir === undefined ? undefined : manifestOf(dir)
127
+ return { real: rel, pkg: pkg && { ...pkg, via: path } }
128
+ })
129
+ }
130
+
131
+ // A node_modules-scope artifact carries node_modules alone; a link into a dependency counts as that dependency.
132
+ function artifactContents({ modules, formats, config }, linkOf) {
133
+ const scope = config?.scope ?? 'full'
134
+ const inScope = (path) => scope === 'full' || hasNodeModulesSegment(path)
135
+ const paths = moduleFileKeys(modules, { scope })
136
+ for (const file of formats?.keys() ?? []) if (inScope(file)) paths.add(file)
137
+ const isPackage = ([dir, info]) => Object.keys(info.files).length > 0 && inScope(dir) && dependencyEcosystem(dir, info.ecosystem) !== undefined
138
+ const packages = [...modules].filter(isPackage).map(([dir, { name, version }]) => ({ dir, name, version: version ?? undefined }))
139
+ const dirs = new Set(packages.map(({ dir }) => dir))
140
+ const links = new Map()
141
+ for (const path of paths) {
142
+ const link = linkOf(path)
143
+ if (link === undefined) continue
144
+ links.set(path, link.real)
145
+ if (link.pkg !== undefined && !dirs.has(link.pkg.dir)) {
146
+ dirs.add(link.pkg.dir)
147
+ packages.push(link.pkg)
148
+ }
149
+ }
150
+ return { paths, packages, links }
151
+ }
152
+
153
+ class Policy {
154
+ #rules = new Map()
155
+ // The rules as given, each list deduped and sorted.
156
+ #given = {}
157
+
158
+ constructor(label, config) {
159
+ this.label = label
160
+ for (const key of POLICY_KEYS) {
161
+ const patterns = config[key]
162
+ if (patterns === undefined) continue
163
+ if (!Array.isArray(patterns) || patterns.some((pattern) => typeof pattern !== 'string' || pattern === '')) {
164
+ throw new TypeError(`${label}: ${key} must be an array of non-empty strings`)
165
+ }
166
+ const compileOne = PATH_KEYS.has(key) ? pathPattern : modulePattern
167
+ this.#rules.set(key, patterns.map((pattern) => compileOne(`${label}: ${key}`, pattern)))
168
+ this.#given[key] = [...new Set(patterns)].toSorted()
169
+ }
170
+ }
171
+
172
+ get key() {
173
+ return JSON.stringify(this.#given)
174
+ }
175
+
176
+ withLabel(label) {
177
+ return new Policy(label, this.#given)
178
+ }
179
+
180
+ // A path is checked as its link's target too; a dependency by its package.json name and its install name:
181
+ // refused if a disallowing rule matches either, allowed only if an allowing rule matches both.
182
+ #problems({ paths, packages, links = new Map() }) {
183
+ const problems = []
184
+ for (const [key, patterns] of this.#rules) {
185
+ const allowing = ALLOWING.has(key)
186
+ const isPath = PATH_KEYS.has(key)
187
+ const offenders = []
188
+ for (const item of isPath ? paths : packages) {
189
+ const names = isPath ? [item, links.get(item)] : [item.name, installedName(item.dir)]
190
+ const matches = names.filter((name) => name !== undefined).map((name) => patterns.find(({ test }) => test(name)))
191
+ const match = matches.find((found) => found !== undefined)
192
+ if (allowing ? matches.includes(undefined) : match !== undefined) offenders.push({ item, by: allowing ? '' : ` (${JSON.stringify(match.pattern)})` })
193
+ }
194
+ if (offenders.length === 0) continue
195
+ const texts = isPath
196
+ ? sortedByPath(offenders, ({ item }) => item).map(({ item, by }) => `${item}${links.has(item) ? ` (a link to ${links.get(item)})` : ''}${by}`)
197
+ : offenders.map(({ item, by }) => `${packageText(item)}${by}`)
198
+ const many = `${texts.length} ${isPath ? 'paths' : 'packages'}: ${listed(texts)}`
199
+ if (allowing) problems.push(texts.length === 1 ? `${key} does not allow ${texts[0]}` : `${key} allows none of ${many}`)
200
+ else problems.push(`${key} refuses ${texts.length === 1 ? texts[0] : many}`)
201
+ }
202
+ return problems
203
+ }
204
+
205
+ assert(contents, hint = '') {
206
+ const problems = this.#problems(contents)
207
+ if (problems.length > 0) throw new Error(`${this.label}: ${problems.join('; ')}${hint}`)
208
+ }
209
+
210
+ assertArtifact(artifact, { hint, links }) {
211
+ this.assert(artifactContents(artifact, links), hint)
212
+ }
213
+
214
+ assertPath(path, pkg, link) {
215
+ const packages = pkg === undefined ? [] : [pkg]
216
+ if (link?.pkg !== undefined && link.pkg.dir !== pkg?.dir) packages.push(link.pkg)
217
+ this.assert({ paths: [path], packages, links: link === undefined ? new Map() : new Map([[path, link.real]]) })
218
+ }
219
+ }
220
+
221
+ export const parsePolicy = (label, config) =>
222
+ (config === null || typeof config !== 'object' || !POLICY_KEYS.some((key) => Object.hasOwn(config, key)) ? null : new Policy(label, config))