@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.
@@ -1,66 +1,277 @@
1
1
  import { isUtf8 } from 'node:buffer'
2
- import { existsSync, readFileSync } from 'node:fs'
3
- import { dirname, isAbsolute, join, relative, resolve } from 'node:path'
4
- import { findPackageJSON } from 'node:module'
5
- import { pathToFileURL } from 'node:url'
2
+ import { dirname, join, posix, relative, resolve } from 'node:path'
6
3
 
7
- import { assertRealPathWithinBase, toPosix } from './util.js'
4
+ import { isValidRepoField } from './bundle.js'
5
+ import { posixPathEscapes } from './artifact-util.js'
6
+ import { diskHost } from './host.js'
7
+ import { assertRealPathWithinBase, hasNodeModulesSegment, relativeEscapes, toPosix } from './util.js'
8
8
 
9
- export function packageType(file) {
10
- const pkg = findPackageJSON(pathToFileURL(file).toString())
9
+ // Text as Node reads a package.json: UTF-8, past a byte order mark.
10
+ const utf8 = new TextDecoder()
11
+ export const packageJSONText = (bytes) => utf8.decode(bytes)
12
+
13
+ export function packageType(file, host = diskHost) {
14
+ const pkg = host.findPackageJSON(file)
11
15
  if (!pkg) return null
12
16
  try {
13
- const type = JSON.parse(readFileSync(pkg, 'utf8')).type
17
+ const type = JSON.parse(packageJSONText(host.readFile(pkg))).type
14
18
  return type === 'module' || type === 'commonjs' ? type : null
15
19
  } catch {
16
20
  return null
17
21
  }
18
22
  }
19
23
 
20
- // Nearest package.json (walking up) with both name and version; pkgDir is relative to baseDir ("." at the root). Null if none.
21
- export function findPackageMetadata(baseDir, fileRelPath) {
22
- let dir = dirname(fileRelPath)
23
- while (true) {
24
- const pkgPath = join(baseDir, dir, 'package.json')
25
- if (existsSync(pkgPath)) {
26
- try {
27
- const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'))
28
- if (pkg.name && pkg.version) return { pkgDir: dir, name: pkg.name, version: pkg.version }
29
- } catch { /* malformed -- keep walking */ }
24
+ // Nearest package.json (walking up) that identifies a bucket; pkgDir is relative to baseDir ("."
25
+ // at the root). Inside node_modules both name and version are required; a workspace package
26
+ // outside node_modules may omit version (the name alone claims the bucket, matching
27
+ // State#locateModule), and a node_modules one's `ecosystem` (npm) and `repo`, where its `repository`
28
+ // names a GitHub one (packageRepo). Null if none. A malformed one is walked past, or with `strict` throws
29
+ // (its files would otherwise land in the parent package); `check`, `host`: see readPackageJson.
30
+ export function findPackageMetadata(baseDir, fileRelPath, { strict = false, check, host = diskHost } = {}) {
31
+ for (let dir = dirname(fileRelPath); ; dir = dirname(dir)) {
32
+ const pkg = readPackageJson(baseDir, toPosix(join(dir, 'package.json')), { strict, check, host })
33
+ const inNodeModules = hasNodeModulesSegment(toPosix(dir))
34
+ if (pkg?.name && (pkg.version || !inNodeModules)) {
35
+ const repo = inNodeModules ? packageRepo(pkg) : undefined
36
+ // `?? undefined` folds a literal `"version": null` into the one absent-version spelling.
37
+ return { pkgDir: dir, name: pkg.name, version: pkg.version ?? undefined, ...(inNodeModules ? { ecosystem: 'npm' } : {}), ...(repo === undefined ? {} : { repo }) }
30
38
  }
31
- if (dir === '.' || dir === '/' || dir === '') return null
32
- const parent = dirname(dir)
33
- if (parent === dir) return null
34
- dir = parent
39
+ if (dir === '.' || dir === '/' || dir === '' || dirname(dir) === dir) return null
40
+ }
41
+ }
42
+
43
+ // The error codes that mean nothing is at a path.
44
+ export const NO_ENTRY = new Set(['ENOENT', 'ENOTDIR'])
45
+
46
+ // Why `file` can't be read, where `host.stat` gave null, or null when nothing is there (a missing
47
+ // path, one through a file, a link to nothing). host.stat answers null for any failure, as Node's
48
+ // module lookup does; real stat tells them apart: a link loop, a directory that may not be searched
49
+ // or a name too long is something there that can't be read, and a read meets the same error.
50
+ function readFailure(host, file) {
51
+ try {
52
+ host.readFile(file)
53
+ } catch (err) {
54
+ return NO_ENTRY.has(err.code) ? null : err
55
+ }
56
+ return new Error(`${file} could be read but not stat'ed`)
57
+ }
58
+
59
+ // host.stat as real stat answers: null only when nothing is there (readFailure); anything else that
60
+ // can't be stat'ed throws, naming the file `label`.
61
+ export function statStrict(host, file, label) {
62
+ const stat = host.stat(file)
63
+ if (stat !== null) return stat
64
+ const failure = readFailure(host, file)
65
+ if (failure === null) return null
66
+ throw new Error(`${label}: can't be read (${failure.code ?? failure.message})`, { cause: failure })
67
+ }
68
+
69
+ // host.stat for a package.json, as Node's lookups read one: null when nothing is there, and one that
70
+ // can't be read (a link loop, a directory that may not be searched) throws ERR_INVALID_PACKAGE_CONFIG,
71
+ // as Node refuses it.
72
+ export function packageJSONStat(host, file) {
73
+ const stat = host.stat(file)
74
+ if (stat !== null) return stat
75
+ const cause = readFailure(host, file)
76
+ if (cause === null) return null
77
+ throw Object.assign(new Error(`Cannot read package config ${file}: ${cause.code ?? cause.message}.`, { cause }), { code: 'ERR_INVALID_PACKAGE_CONFIG' })
78
+ }
79
+
80
+ // `file`'s bytes, read through `host`, or null when there's no file (a directory counts as none).
81
+ // It's read only when it's a regular file: a FIFO, a socket, a device or a link to one
82
+ // (`/dev/stdin`) throws, naming it `label`, rather than stalling or reading the process's input, and
83
+ // so does one there that can't be read (statStrict).
84
+ export function readRegularFileOrNull(file, label, host = diskHost) {
85
+ const stat = statStrict(host, file, label)
86
+ if (stat === null || stat.isDirectory()) return null
87
+ if (!stat.isFile()) throw new Error(`${label}: not a regular file`)
88
+ return host.readFile(file)
89
+ }
90
+
91
+ // The package.json at `rel` (under `baseDir`), parsed (a leading byte-order mark skipped, as npm
92
+ // and Node skip it), read through `host`; null when there's none (a directory counts as none), or
93
+ // when it doesn't parse, isn't a regular file or can't be read -- unless `strict`, then that throws
94
+ // (only nothing there is no package.json, as Node reads one: statStrict), saying where
95
+ // with the parser's line and column but never its message, which quotes the text (a file that isn't
96
+ // JSON may be anything, a secret included). `check(rel)`, when given, sees the path before it is
97
+ // read, and may throw to refuse it.
98
+ export function readPackageJson(baseDir, rel, { strict = false, check, host = diskHost } = {}) {
99
+ const file = join(baseDir, rel)
100
+ const stat = strict ? statStrict(host, file, rel) : host.stat(file)
101
+ if (stat === null || stat.isDirectory()) return null
102
+ check?.(rel)
103
+ try {
104
+ // A FIFO, a socket or a device (or a link to one) is never read: it could stall the bundle.
105
+ if (!stat.isFile()) throw new Error(`${rel}: not a regular file`)
106
+ const bytes = host.readFile(file)
107
+ // Strict, it's read as the file's own text or not at all; lenient lookups decode it as they always
108
+ // have (a stray byte as U+FFFD).
109
+ if (strict && !isUtf8(bytes)) throw new Error(`${rel}: not valid UTF-8`)
110
+ return parseJson(packageJSONText(bytes), rel)
111
+ } catch (err) {
112
+ if (strict) throw err
113
+ return null
114
+ }
115
+ }
116
+
117
+ // JSON.parse, throwing where the text breaks (the parser's line and column) but never the parser's
118
+ // message, which quotes the text.
119
+ function parseJson(text, rel) {
120
+ try {
121
+ return JSON.parse(text)
122
+ } catch (err) {
123
+ const at = /\(line \d+ column \d+\)/u.exec(err.message)?.[0]
124
+ // eslint-disable-next-line preserve-caught-error -- the parser's error quotes the file
125
+ throw new Error(`${rel} is not valid JSON${at ? ` ${at}` : ''}`)
35
126
  }
36
127
  }
37
128
 
38
129
  export function normalizeEntries(entries, cwd) {
39
130
  const baseDir = resolve(cwd)
40
131
  return entries.map((e) => {
41
- const abs = resolve(cwd, e)
42
- const rel = toPosix(relative(baseDir, abs))
43
- // On Windows path.relative() returns an absolute path across drives (no leading '..'), so reject that form too.
44
- if (rel.startsWith('..') || isAbsolute(rel)) throw new Error(`Entry escapes baseDir: ${e}`)
132
+ const rel = toPosix(relative(baseDir, resolve(cwd, e)))
133
+ if (relativeEscapes(rel)) throw new Error(`Entry escapes baseDir: ${e}`)
45
134
  return rel.replace(/^\.\//u, '')
46
135
  })
47
136
  }
48
137
 
49
- // Bytes of a bundled module's `package.json`, or null to skip when it's absent on disk; non-UTF-8 aborts (never silently skipped).
50
- export function readModuleManifest({ baseDir, realBase, rel } = {}) {
138
+ // Bytes of a bundled module's `package.json`, or null to skip when it's absent; one that can't be
139
+ // read (statStrict) or isn't UTF-8 aborts (never silently skipped).
140
+ export function readModuleManifest({ baseDir, realBase, rel, host = diskHost } = {}) {
51
141
  const absolute = join(baseDir, rel)
52
- if (!existsSync(absolute)) return null
53
- assertRealPathWithinBase(realBase, baseDir, rel)
54
- const buf = readFileSync(absolute)
142
+ if (statStrict(host, absolute, rel) === null) return null
143
+ assertRealPathWithinBase(realBase, baseDir, rel, host)
144
+ const buf = host.readFile(absolute)
55
145
  if (!isUtf8(buf)) throw new Error(`package.json is not valid UTF-8: ${rel}`)
56
146
  return buf
57
147
  }
58
148
 
59
149
  // Never throws: a missing/unreadable/malformed file yields null.
60
- export function readJson(file) {
150
+ export function readJson(file, host = diskHost) {
151
+ try {
152
+ return JSON.parse(packageJSONText(host.readFile(file)))
153
+ } catch {
154
+ return null
155
+ }
156
+ }
157
+
158
+ // `owner/name` from a package.json `repository` (GitHub URL or shorthand), else null. A `#committish`
159
+ // npm lets it name is no part of the repo; a URL's userinfo holds only what RFC 3986 allows there, so
160
+ // a `?` or `\` ending the authority early (`https://evil.example?@github.com/a/b`) isn't GitHub's. An
161
+ // scp-like `git@github.com:owner/name` is taken behind an `ssh://` too (`git+ssh://git@github.com:o/n`),
162
+ // as package.json files spell it.
163
+ export function parseGithubRepository(url) {
164
+ if (typeof url !== 'string') return null
165
+ const match = /^(?:github:|(?:git\+)?(?:(?:https?|ssh|git):\/\/(?:[\w.~%!$&'()*+,;=:-]*@)?github\.com(?::\d+)?\/|ssh:\/\/(?:[\w.~%!$&'()*+,;=-]*@)?github\.com:|(?:[^@/:]+@)?github\.com:))?([\w.-]+)\/([\w.-]+?)(?:\.git)?\/?$/iu.exec(url.trim().replace(/#.*$/su, ''))
166
+ // Must also pass the bundle format's `github` check.
167
+ const github = match && `${match[1]}/${match[2]}`
168
+ return github && isValidRepoField('github', github) ? github : null
169
+ }
170
+
171
+ // Best-effort `origin` url: literal match of git's own `.git/config` layout, no parsing.
172
+ const GIT_ORIGIN_URL = '[remote "origin"]\n\turl = '
173
+ export function gitOriginUrl(text) {
174
+ const at = text?.indexOf(GIT_ORIGIN_URL) ?? -1
175
+ if (at === -1) return null
176
+ const start = at + GIT_ORIGIN_URL.length
177
+ const end = text.indexOf('\n', start)
178
+ return text.slice(start, end === -1 ? undefined : end).trim() || null
179
+ }
180
+
181
+ // The text of `file`, or null. Read through `host` (never the --fs-patched fs), it is never captured.
182
+ export const readText = (host, file) => {
61
183
  try {
62
- return JSON.parse(readFileSync(file, 'utf8'))
184
+ return host.readFile(file).toString('utf8')
63
185
  } catch {
64
186
  return null
65
187
  }
66
188
  }
189
+
190
+ // Dir of a `https://github.com/<github>/tree/<branch>/<dir>` homepage (one-segment branch).
191
+ export function githubHomepageDirectory(homepage, github) {
192
+ if (typeof homepage !== 'string') return undefined
193
+ const match = /^https?:\/\/(?:www\.)?github\.com\/([^/]+\/[^/]+)\/tree\/[^/#?]+\/([^#?]+)/iu.exec(homepage.trim())
194
+ if (!match || match[1].toLowerCase() !== github.toLowerCase()) return undefined
195
+ try {
196
+ return decodeURIComponent(match[2])
197
+ } catch {
198
+ return undefined
199
+ }
200
+ }
201
+
202
+ // `{ directory }` where it is a valid one, else `{}`.
203
+ const repoLocation = (directory) => (isValidRepoField('directory', directory) ? { directory } : {})
204
+
205
+ // A package.json's declared `base` (its `repository.directory`) joined with `rel` as a `repoLocation`;
206
+ // `{}` where none is declared (unknown, not the root), or where it comes to the root: `directory: ''`
207
+ // is recorded from a layout read (detectRepo's git step), never a manifest's claim. Windows users
208
+ // write `base` with `\`: metadata, not a name on disk, so its `\` is taken for a separator.
209
+ const declaredLocation = (base, rel) => {
210
+ if (typeof base !== 'string') return {}
211
+ const directory = posix.join(base.replaceAll('\\', '/'), rel).replace(/^\/+|\/+$/gu, '')
212
+ return directory === '' || directory === '.' ? {} : repoLocation(directory) // `/`, `./`, `a/../`
213
+ }
214
+
215
+ // Git and common dirs, following a worktree/submodule `.git` file.
216
+ function gitDirs(dotGit, host) {
217
+ const pointer = readText(host, dotGit) // null for a `.git` directory (EISDIR)
218
+ const gitDir = pointer?.startsWith('gitdir: ') ? resolve(dirname(dotGit), pointer.slice('gitdir: '.length).trim()) : dotGit
219
+ const common = readText(host, join(gitDir, 'commondir'))?.trim()
220
+ return { gitDir, commonDir: common ? resolve(gitDir, common) : gitDir }
221
+ }
222
+
223
+ // HEAD's commit: detached sha, loose ref, or packed-refs; undefined unless a valid sha.
224
+ function gitHeadCommit({ gitDir, commonDir }, host) {
225
+ const head = readText(host, join(gitDir, 'HEAD'))?.trim()
226
+ if (!head) return undefined
227
+ let commit = head
228
+ if (head.startsWith('ref: ')) {
229
+ const ref = head.slice('ref: '.length)
230
+ if (!ref.startsWith('refs/') || posixPathEscapes(ref)) return undefined
231
+ commit = readText(host, join(commonDir, ref))?.trim() ??
232
+ readText(host, join(commonDir, 'packed-refs'))?.split('\n').find((line) => line.endsWith(` ${ref}`))?.split(' ')[0]
233
+ }
234
+ return isValidRepoField('commit', commit) ? commit : undefined
235
+ }
236
+
237
+ // A parsed package.json's `repository` url (the string shorthand, or its `url`), or undefined.
238
+ function repositoryUrl(json) {
239
+ const repository = json?.repository
240
+ const url = typeof repository === 'string' ? repository : repository?.url
241
+ return typeof url === 'string' ? url : undefined
242
+ }
243
+
244
+ // The `repo` a parsed package.json's `repository` names for `rel`, a directory below it ('' for its
245
+ // own): `github` from its GitHub URL or shorthand, and `directory` from `repository.directory` joined
246
+ // with `rel` (declaredLocation); undefined where it names no GitHub repository.
247
+ export function packageRepo(json, rel = '') {
248
+ const github = parseGithubRepository(repositoryUrl(json))
249
+ if (!github) return undefined
250
+ // Often unset; fall back to a GitHub tree `homepage`.
251
+ const base = typeof json.repository.directory === 'string' ? json.repository.directory : githubHomepageDirectory(json.homepage, github)
252
+ return { github, ...declaredLocation(base, rel) }
253
+ }
254
+
255
+ // Bundle `repo` for `dir`: git origin/HEAD at the work tree root, with `dir`'s place in it (`''` at
256
+ // the root), else nearest package.json `repository` (packageRepo).
257
+ export function detectRepo(dir, host = diskHost) {
258
+ const start = resolve(dir)
259
+ let pkg = null // null: no package.json `repository` seen yet; undefined: one seen, not GitHub
260
+ for (let cursor = start; ; cursor = dirname(cursor)) {
261
+ const rel = toPosix(relative(cursor, start))
262
+ if (pkg === null) {
263
+ const json = readJson(join(cursor, 'package.json'), host)
264
+ if (repositoryUrl(json) !== undefined) pkg = packageRepo(json, rel)
265
+ }
266
+ const dotGit = join(cursor, '.git')
267
+ if (host.stat(dotGit) !== null) {
268
+ const dirs = gitDirs(dotGit, host)
269
+ const github = parseGithubRepository(gitOriginUrl(readText(host, join(dirs.commonDir, 'config'))))
270
+ if (github) return stripUndefined({ github, ...repoLocation(rel), commit: gitHeadCommit(dirs, host) })
271
+ return pkg ?? undefined
272
+ }
273
+ if (dirname(cursor) === cursor) return pkg ?? undefined
274
+ }
275
+ }
276
+
277
+ const stripUndefined = (obj) => Object.fromEntries(Object.entries(obj).filter(([, v]) => v !== undefined))