@preventive/upstream 1.0.0-alpha.9 → 1.0.1

package/src/npm/versions.js

@@ -0,0 +1,97 @@
+import assert from 'node:assert/strict'
+
+import { assertArgs, assertion, matches, show } from '../args.js'
+import { readJSON, writeJSON } from '../cache.js'
+import { NPM_REGISTRY, buildUrl, isNotFound, recover } from '../http.js'
+import { getDocument } from './registry.js'
+
+const DIR = 'npm/versions' // No expiry: the registry never takes a version twice, nor changes its dist.
+// One sha512 and nothing else, as the registry writes it: a sha1, a second
+// hash or an option is refused rather than trusted. 64 bytes leave the
+// last character before `==` two bits, so only A, Q, g or w is canonical.
+const assertIntegrity = assertion('"sha512-" and a base64 sha512', matches(/^sha512-[\dA-Za-z+/]{85}[AQgw]==$/u))
+
+// `{ tarball, integrity }` and nothing else, the tarball exactly the
+// registry's own URL for that version. Each field is read once, and only
+// as the object's own, into a copy that is checked and used from then on:
+// the caller's object can change while a request is out, and a field on
+// its prototype is not one it has.
+export function checkedDist(method, name, version, dist) {
+  assertArgs(method, dist, { tarball: null, integrity: null }, 'dist')
+  const [tarball, integrity] = ['tarball', 'integrity'].map((key) => (Object.hasOwn(dist, key) ? dist[key] : undefined))
+  assertIntegrity(method, 'dist.integrity', integrity)
+  const segments = name.split('/')
+  const expected = buildUrl(NPM_REGISTRY, [...segments, '-', `${segments.at(-1)}-${version}.tgz`])
+  assert.ok(tarball === expected, `${method}: dist.tarball must be ${expected}, got ${show(tarball)}`)
+  return { tarball, integrity }
+}
+
+const distOf = (method, name, version, json) => checkedDist(method, name, version, { tarball: json.dist?.tarball, integrity: json.dist?.integrity })
+
+// Whether a version document is one to keep, or to take as kept: for that
+// name and version, with a dist that passes.
+function isKeepable(method, name, version, json) {
+  if (json?.name !== name || json.version !== version) return false
+  try {
+    distOf(method, name, version, json)
+    return true
+  } catch {
+    return false
+  }
+}
+
+// A version's document as `cache` keeps it (readJSON), or none.
+async function keptDocument(method, name, version, cache) {
+  const json = await readJSON(DIR, `${name}@${version}`, cache)
+  return isKeepable(method, name, version, json) ? json : undefined
+}
+
+// The registry's document, kept whole in `cache` once it is keepable; one
+// whose dist is refused is answered all the same.
+async function keepDocument(method, name, version, json, cache) {
+  assert.ok(json.version === version, `${method}: the registry answered for ${name}@${show(json.version)}, not ${name}@${version}`)
+  if (isKeepable(method, name, version, json)) await writeJSON(DIR, `${name}@${version}`, json, cache)
+  return json
+}
+
+const fetchDocument = async (method, name, version, cache) => await keepDocument(method, name, version, await getDocument(method, name, version), cache)
+
+// A version's document, kept or else fetched, for what is not an
+// integrity: a package's repo (advisories.js), as trusted as setCacheDir's
+// repo records are. Null where the registry does not have that version:
+// its 404 alone, never a failure of the cache's.
+export async function getVersionDocument(method, name, version, cache) {
+  const kept = await keptDocument(method, name, version, cache)
+  if (kept) return kept
+  const json = await getDocument(method, name, version).catch(recover(isNotFound, null))
+  return json && await keepDocument(method, name, version, json, cache)
+}
+
+// The dist of a version document a cache answers, where it is that
+// version's, its dist passes, and its tarball and integrity are `given`'s
+// (checkedDist): a cache never supplies a dist, only confirms one.
+export function matchingDist(method, name, version, json, given) {
+  if (!isKeepable(method, name, version, json)) return undefined
+  const dist = distOf(method, name, version, json)
+  return dist.integrity === given.integrity && dist.tarball === given.tarball ? dist : undefined
+}
+
+// A version's document, and its dist checked. A kept document is read only
+// for a caller that already has a dist, `given`, and answers with no
+// request where it matches (matchingDist). Else, or without one, the
+// registry is asked, and its document, kept in place of any other, throws
+// where it does not.
+export async function getVersion(method, name, version, given, cache) {
+  if (given !== undefined) {
+    const kept = await readJSON(DIR, `${name}@${version}`, cache)
+    const dist = matchingDist(method, name, version, kept, given)
+    if (dist) return { dist, json: kept }
+  }
+  const json = await fetchDocument(method, name, version, cache)
+  const dist = distOf(method, name, version, json)
+  if (given !== undefined) {
+    assert.ok(dist.integrity === given.integrity, `${method}: ${name}@${version} is ${dist.integrity} on the registry, not ${given.integrity}`)
+    assert.ok(dist.tarball === given.tarball, `${method}: ${name}@${version} is at ${dist.tarball} on the registry, not ${given.tarball}`)
+  }
+  return { dist, json }
+}

package/src/package.js

@@ -1,7 +1,7 @@
 import assert from 'node:assert/strict'
 
 import { assertion, isRepo, isRepoPath, sameName } from './args.js'
-import { githubRepoOfUrl } from './remote.js'
+import { githubRepoOfUrl, withoutDotGit } from './remote.js'
 
 const bugsRegex = /^(?i:https?:\/\/github\.com)(?::\d{1,5})?\/(?<repo>[\w-]+\/[\w.-]+)\/issues\/?$/u
 // npm's `owner/name` shorthand means GitHub. No dots in the owner, so a
@@ -11,9 +11,12 @@ const shorthandRegex = /^(?:github:)?(?<repo>[\w-]+\/[\w.-]+)$/u
 // The ref is one segment: a branch with a `/` reads as part of the directory.
 const homepageRegex = /^(?:https?:\/\/)?(?:www\.)?github\.com(?::\d{1,5})?\/(?<repo>[\w-]+\/[\w.-]+?)(?:\.git)?(?:\/(?:tree\/[^/]+(?:\/(?<directory>.*))?)?)?$/iu
 const str = (value) => (typeof value === 'string' ? value : '')
-const urlOf = (field) => str(field?.url ?? field)
+// Read past the whitespace around it, as `homepage` is.
+const urlOf = (field) => str(field?.url ?? field).trim()
 const homepageUrl = (homepage) => str(homepage).trim().split(/[?#]/u)[0] // npm appends `#readme`.
-const repoIn = (regex, text) => regex.exec(text)?.groups.repo
+// Every trailing `.git` dropped, as the URLs' are: no answer ends in one
+// (the npm repo cache refuses one).
+const repoIn = (regex, text) => withoutDotGit(regex.exec(text)?.groups.repo)
 // A URL's path spells a tree path percent-encoded; one that does not decode names none.
 function decodePath(path = '') {
   try {
@@ -33,6 +36,19 @@ function repoSubdirectory(value) {
   return isRepoPath(path) ? path : undefined // No empty, `.`, `..` or `.git` part: a path inside the repo.
 }
 
+// `repository.directory` is a path its author may write with Windows' `\`.
+// A tree path is `/`-separated: a `\` is a name's own only in a homepage's
+// (`%5C`), which is the path itself. Its empty and `.` parts are dropped
+// (`./a//b/.` is `a/b`), and one of nothing else (`./`, `/`, `/.`, `.`, `''`)
+// declares the repo's root, `''`; one with a `..` part names none, whatever
+// it would come to. A package.json that declares none says nothing of where
+// in the repo it sits.
+function declaredDirectory(value) {
+  if (typeof value !== 'string') return undefined
+  const parts = value.replaceAll('\\', '/').split('/').filter((part) => part !== '' && part !== '.')
+  return parts.length === 0 ? '' : repoSubdirectory(parts.join('/'))
+}
+
 export const isRepoDirectory = (value) => typeof value === 'string' && (value === '' || repoSubdirectory(value) === value)
 export const assertRepoDirectory = assertion('a path inside the repository', isRepoDirectory)
 
@@ -41,11 +57,12 @@ export function getRepo(pkg) {
   const { bugs, repository } = pkg
   const declared = repositoryRepo(urlOf(repository))
   const homepage = homepageRegex.exec(homepageUrl(pkg.homepage))?.groups
+  const homepageRepo = withoutDotGit(homepage?.repo)
   // `repository` first: it is the field a publisher maintains, where a
   // `bugs` tracker can be left pointing at a former owner or misspelt.
-  const github = [declared, repoIn(bugsRegex, urlOf(bugs)), homepage?.repo].find(isRepo)
+  const github = [declared, repoIn(bugsRegex, urlOf(bugs)), homepageRepo].find(isRepo)
   if (github === undefined) return {}
-  const directory = (sameName(declared, github) && repoSubdirectory(repository?.directory))
-    || (sameName(homepage?.repo, github) && repoSubdirectory(decodePath(homepage.directory)))
-  return { github, ...(directory && { directory }), url: `https://github.com/${github}` }
+  const directory = (sameName(declared, github) ? declaredDirectory(repository?.directory) : undefined)
+    ?? (sameName(homepageRepo, github) ? repoSubdirectory(decodePath(homepage.directory)) : undefined)
+  return { github, ...(directory !== undefined && { directory }), url: `https://github.com/${github}` }
 }

package/src/remote.js

@@ -1,15 +1,22 @@
 import { isRepo } from './args.js'
 
 // `user:token@` is skipped, never returned. It is held to the characters
-// RFC 3986 allows there — a `#`, `?` or `\` before the `@` ends the
+// RFC 3986 allows there -- a `#`, `?` or `\` before the `@` ends the
 // authority early, so `https://evil.example#@github.com/a/b` goes to
-// evil.example — and URL parsing has to agree the host is github.com.
+// evil.example -- and URL parsing has to agree the host is github.com.
 const gitUrlRegex = /^(?i:(?:git\+)?(?:https?|git|ssh)):\/\/(?:[\w.~%!$&'()*+,;=:-]*@)?(?i:github\.com)(?::\d{1,5})?\/(?<repo>[\w-]+\/[\w.-]+?)(?:\.git)?\/?$/u
 const scpRegex = /^(?i:git\+ssh:\/\/)?git@(?i:github\.com):(?<repo>[\w-]+\/[\w.-]+?)(?:\.git)?$/u
 
+// A repo with every trailing `.git` dropped, so none ends in one: in a loop,
+// as a regex would backtrack over a long run of them in a crafted URL.
+export function withoutDotGit(repo) {
+  while (repo?.endsWith('.git')) repo = repo.slice(0, -4)
+  return repo
+}
+
 export function githubRepoOfUrl(url) {
   if (typeof url !== 'string') return undefined
   const onGitHub = URL.parse(url.replace(/^git\+/iu, ''))?.hostname.toLowerCase() === 'github.com'
-  const repo = scpRegex.exec(url)?.groups.repo ?? (onGitHub ? gitUrlRegex.exec(url)?.groups.repo : undefined)
+  const repo = withoutDotGit(scpRegex.exec(url)?.groups.repo ?? (onGitHub ? gitUrlRegex.exec(url)?.groups.repo : undefined))
   return isRepo(repo) ? repo : undefined
 }