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