@preventive/upstream 1.0.0-alpha.3 → 1.0.0-alpha.5

package/src/advisories/osv.js

@@ -13,6 +13,12 @@ const QUERIES_PER_REQUEST = 1000
 const RECORDS_AT_ONCE = 8
 const isOsvId = matches(/^(?=.{1,128}$)[A-Z][\dA-Z]*(?:-[\dA-Za-z]+)+$/u)
 const INFORMATIONAL = new Set(['unmaintained', 'unsound', 'notice'])
+// Of the records that publish one advisory, the first answered for a
+// version stands for the rest on it: RustSec's, what `cargo audit` reads
+// and GitHub mirrors, then the GHSA, then any other (MAL-…), then by id.
+const rank = (id) => (id.startsWith('RUSTSEC-') ? 0 : (isGhsa(id) ? 1 : 2))
+const first = (a, b) => rank(a.id) - rank(b.id) || order(a.id, b.id)
+const named = (a, b) => a.aliases.includes(b.id) || b.aliases.includes(a.id)
 
 export const CARGO = {
   osv: 'crates.io',
@@ -20,7 +26,6 @@ export const CARGO = {
   lookUp: crateRepos,
   assertName: assertCrateName,
   assertVersion: assertCrateVersion,
-  keep: (id) => id.startsWith('RUSTSEC-'), // What `cargo audit` reads; the GHSA records mirror it.
   advisories: (asked, options) => osvAdvisories(CARGO, asked, options),
 }
 // TODO: packagist.org's API, what `composer audit` reads, also has the
@@ -70,11 +75,13 @@ function toAdvisory(ecosystem, name, versions, record) {
 }
 
 // OSV's batch query matches versions on its side, but answers ids only:
-// each record is fetched once after. A record another database also
-// publishes comes back under both ids, so one that aliases a GHSA keeps
-// only the versions that GHSA was not answered for.
+// each record is fetched once after. An advisory more than one database
+// publishes comes back under each one's id, the records naming each other
+// as aliases, either way round, directly or through others: one group, in
+// which each version is reported under the first answered for it, and
+// each record has the others' ids as aliases.
 async function osvAdvisories(ecosystem, asked, options) {
-  const { osv, github, lookUp, covers, keep = () => true } = ecosystem
+  const { osv, github, lookUp, covers } = ecosystem
   const list = [...asked].flatMap(([name, versions]) => versions.map((version) => ({ name, version })))
   const hits = new Map() // id → name → versions, in `list` order
   for (const chunk of chunks(list, QUERIES_PER_REQUEST)) {
@@ -85,21 +92,28 @@ async function osvAdvisories(ecosystem, asked, options) {
       const { name, version } = chunk[j]
       const vulns = result?.vulns ?? []
       assert.ok(result && result.next_page_token === undefined && Array.isArray(vulns) && vulns.every((vuln) => isOsvId(vuln?.id)), `advisories: malformed OSV result for ${name}@${version}`)
-      for (const { id } of vulns.filter((vuln) => keep(vuln.id))) {
+      for (const { id } of vulns) {
         const byName = hits.get(id) ?? hits.set(id, new Map()).get(id)
         byName.set(name, (byName.get(name) ?? new Set()).add(version))
       }
     }
   }
   const records = (await pool([...hits.keys()], RECORDS_AT_ONCE, getVuln)).filter((record) => !record.withdrawn)
-  const live = new Set(records.map((record) => record.id))
+  const groups = new Map()
+  for (const record of records) {
+    if (groups.has(record)) continue
+    const group = [record]
+    for (const member of group) group.push(...records.filter((other) => !group.includes(other) && named(member, other)))
+    for (const member of group) groups.set(member, group)
+  }
   const rows = []
   for (const record of records) {
+    const group = groups.get(record)
+    const above = group.filter((other) => first(other, record) < 0)
+    const aliases = [...new Set([...record.aliases, ...group.map((other) => other.id)])].filter((id) => id !== record.id)
     for (const [name, versions] of hits.get(record.id)) {
-      // Only the versions a live GHSA it aliases answered for too.
-      const shadowed = isGhsa(record.id) ? [] : record.aliases.filter((alias) => isGhsa(alias) && live.has(alias)).flatMap((alias) => [...(hits.get(alias).get(name) ?? [])])
-      const rest = [...versions].filter((version) => !shadowed.includes(version))
-      if (rest.length > 0) rows.push(toAdvisory(osv, name, rest, record))
+      const rest = [...versions].filter((version) => !above.some((other) => hits.get(other.id).get(name)?.has(version)))
+      if (rest.length > 0) rows.push(toAdvisory(osv, name, rest, { ...record, aliases }))
     }
   }
   rows.sort((a, b) => order(a.name, b.name) || order(a.id, b.id))

package/src/advisories/repos.js

@@ -1,51 +1,24 @@
 import assert from 'node:assert/strict'
-import { setTimeout as sleep } from 'node:timers/promises'
 
-import { isRepo, show } from '../args.js'
-import { readRecord, writeRecord } from '../cache.js'
-import { CRATES_API, PACKAGIST_REPO, buildUrl, isNotFound, recover, request } from '../http.js'
+import { show } from '../args.js'
+import { addRepos, readRepos } from '../cache.js'
+import { lookUpCrateRepos } from '../cargo/repos.js'
+import { PACKAGIST_REPO, SOLDEER_API, buildUrl, isNotFound, recover, request } from '../http.js'
 import { lookUpPackageRepo } from '../npm/repos.js'
-import { chunks, pool } from '../pool.js'
+import { pool } from '../pool.js'
 import { githubRepoOfUrl } from '../remote.js'
 
-const CRATES_PER_REQUEST = 100
-const CRATES_PACE_MS = 1000 // crates.io asks for a request a second at most, and a user agent.
-const USER_AGENT = '@preventive/upstream (https://github.com/PreventiveMeasures/libraries)'
 const PACKAGES_AT_ONCE = 8
 
 // Name → its GitHub repo, or null where the registry has no such package
 // or it names no GitHub repo; any other failure throws. Only a repo found
 // is cached, for a month.
 async function cachedRepos(dir, names, fetchMissing) {
-  const repos = new Map()
-  for (const name of names) {
-    const entry = await readRecord(dir, name)
-    if (isRepo(entry?.github)) repos.set(name, entry.github)
-  }
-  const missing = names.filter((name) => !repos.has(name))
-  for (const [name, github] of await fetchMissing(missing)) {
-    repos.set(name, github)
-    if (github) await writeRecord(dir, name, { github })
-  }
+  const repos = await readRepos(dir, names)
+  await addRepos(dir, repos, await fetchMissing(names.filter((name) => !repos.has(name))))
   return repos
 }
 
-// A crate crates.io leaves out of its answer is one it does not have.
-async function fetchCrates(names) {
-  const found = new Map(names.map((name) => [name, null]))
-  for (const [i, chunk] of chunks(names, CRATES_PER_REQUEST).entries()) {
-    if (i > 0) await sleep(CRATES_PACE_MS)
-    const url = buildUrl(CRATES_API, ['api', 'v1', 'crates'], { 'ids[]': chunk, per_page: CRATES_PER_REQUEST })
-    const answer = await request(url, { as: 'json', headers: { 'User-Agent': USER_AGENT } })
-    assert.ok(Array.isArray(answer?.crates), 'advisories: expected a list of crates from crates.io')
-    for (const crate of answer.crates) {
-      assert.ok(chunk.includes(crate?.id), `advisories: crates.io answered for ${show(crate?.id)}, which was not asked`)
-      found.set(crate.id, githubRepoOfUrl(crate.repository) ?? null)
-    }
-  }
-  return found
-}
-
 async function fetchEach(names, fetch) {
   const found = await pool(names, PACKAGES_AT_ONCE, fetch)
   return new Map(names.map((name, i) => [name, found[i]]))
@@ -61,6 +34,15 @@ async function fetchComposerRepo(name) {
   return githubRepoOfUrl(versions[0]?.source?.url) ?? null
 }
 
-export const crateRepos = (names) => cachedRepos('cargo/repos', names, fetchCrates)
+// Soldeer answers a project it does not have with an empty list.
+async function fetchSoldeerRepo(name) {
+  const answer = await request(buildUrl(SOLDEER_API, ['api', 'v1', 'project'], { project_name: name }), { as: 'json' })
+  assert.ok(Array.isArray(answer?.data), `advisories: expected a list of projects from Soldeer for ${name}`)
+  for (const project of answer.data) assert.ok(project?.name === name, `advisories: Soldeer answered for ${show(project?.name)}, not ${name}`)
+  return githubRepoOfUrl(answer.data[0]?.github_url) ?? null
+}
+
+export const crateRepos = (names) => lookUpCrateRepos('advisories', names)
 export const composerRepos = (names) => cachedRepos('composer/repos', names, (missing) => fetchEach(missing, fetchComposerRepo))
 export const npmRepos = (names) => fetchEach(names, async (name) => (await lookUpPackageRepo(name))?.github ?? null)
+export const soldeerRepos = (names) => cachedRepos('soldeer/repos', names, (missing) => fetchEach(missing, fetchSoldeerRepo))

package/src/args.js

@@ -15,7 +15,9 @@ const isLogin = matches(/^(?=.{1,39}$)[a-z\d](?:-?[a-z\d])*$/iu)
 const isRepoName = matches(/^(?!\.\.?$)[\w.-]{1,100}$/u)
 // `.git` is never in a repo's tree, and no commit should write into it.
 export const isRepoPath = (value) => isString(value, 4096) && value.split('/').every((part) => !['', '.', '..', '.git'].includes(part.toLowerCase()))
-const BAD_REF = /^$|^@$|^-|[ ~^:?*[\\]|\.\.|@\{|^\/|\/$|\/\/|(?:^|\/)\.|\.lock(?:\/|$)|\.$/u // git check-ref-format, a rule per alternative
+// git check-ref-format, a rule per alternative. A tag's name may be `@` or
+// start with `-`; a branch's may not.
+const BAD_REF = /^$|[ ~^:?*[\\]|\.\.|@\{|^\/|\/$|\/\/|(?:^|\/)\.|\.lock(?:\/|$)|\.$/u
 const isToken = matches(/^[!-~]+$/u)
 // npm's rules for existing names: capitals allowed (JSONStream), the
 // legacy `~'!()*` not.
@@ -37,8 +39,10 @@ export function isRepo(value) {
 }
 
 export const isStrings = (value) => Array.isArray(value) && value.every((item) => typeof item === 'string')
+export const isIterable = (value) => typeof value?.[Symbol.iterator] === 'function' && typeof value !== 'string'
 export const sameName = (a, b) => typeof a === 'string' && a.toLowerCase() === b.toLowerCase()
-export const isRefName = (value) => isString(value, 255) && !BAD_REF.test(value)
+export const isTagName = (value) => isString(value, 255) && !BAD_REF.test(value)
+export const isRefName = (value) => isTagName(value) && !/^(?:@$|-)/u.test(value)
 export const isSha = matches(/^(?:[\da-f]{40}|[\da-f]{64})$/u)
 export const isGhsa = matches(/^GHSA(?:-[\da-hj-km-np-tv-z]{4}){3}$/u)
 export const assertion = (must, predicate) => (method, what, value) => assert.ok(predicate(value), `${method}: ${what} must be ${must}, got ${show(value)}`)
@@ -52,6 +56,16 @@ export function assertArgs(method, options, spec, name) {
   for (const [key, check] of Object.entries(spec)) check?.(method, label(key), options[key])
 }
 
+// The names a resolve*Repos call is given, each checked and given once,
+// and its options.
+export function assertNames(method, what, names, options, assertName) {
+  assert.ok(isIterable(names), `${method}: ${what} must be an iterable of names`)
+  assertArgs(method, options, { cachedOnly: optional(assertBoolean) })
+  const unique = [...new Set(names)]
+  for (const name of unique) assertName(method, 'name', name)
+  return unique
+}
+
 export const assertBoolean = assertion('a boolean', (value) => typeof value === 'boolean')
 export const assertNumber = assertion('a positive integer', (value) => Number.isSafeInteger(value) && value > 0)
 export const assertLine = assertion('a non-empty single line', (value) => isString(value, 1024) && value.trim() !== '')
@@ -62,6 +76,7 @@ export const assertLogin = assertion('a GitHub login', isLogin)
 export const assertRepoName = assertion('a repository name', isRepoName)
 export const assertRepo = assertion('"owner/name"', isRepo)
 export const assertRef = assertion('a branch or tag name', isRefName)
+export const assertTagName = assertion('a tag name', isTagName)
 export const assertSha = assertion('a full commit sha', isSha)
 export const isSha1 = matches(/^[\da-f]{40}$/u)
 export const assertTreeId = assertion('a full tree id', isSha1)
@@ -74,5 +89,19 @@ export const assertPackageVersion = assertion('an exact semver version', isExact
 export const assertGhsa = assertion('a GHSA id', isGhsa)
 export const assertCrateName = assertion('a crate name', matches(/^[A-Za-z][\w-]{0,63}$/u))
 export const assertCrateVersion = assertion('a semver version', matches(/^(?=.{5,256}$)(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)(?:-(?:0|[1-9]\d*|\d*[A-Za-z-][\dA-Za-z-]*)(?:\.(?:0|[1-9]\d*|\d*[A-Za-z-][\dA-Za-z-]*))*)?(?:\+[\dA-Za-z-]+(?:\.[\dA-Za-z-]+)*)?$/u))
+// Soldeer's own rule for a name: 3 to 100 of lowercase letters, digits and
+// `-`, starting with one of them or `@`, ending with a letter or digit.
+export const assertSoldeerName = assertion('a Soldeer package name', matches(/^(?=.{3,100}$)[@\da-z][\da-z-]*[\da-z]$/u))
+// Soldeer takes any version but an empty one. Its registry has semver
+// (`5.7.0-rc.0`, `1.0.2-solc-0.8-simulate`), bare numbers and commit hashes.
+export const assertSoldeerVersion = assertion('letters, digits, `.`, `_`, `+` and `-`', matches(/^(?=.{1,128}$)[\dA-Za-z][\w.+-]*$/u))
+// A package's name and version, as a registry's getters take them.
+const assertNameVersion = (assertName, assertVersion) => (method, name, version) => {
+  assertName(method, 'name', name)
+  assertVersion(method, 'version', version)
+}
+export const assertCrate = assertNameVersion(assertCrateName, assertCrateVersion)
+export const assertPackage = assertNameVersion(assertPackageName, assertPackageVersion)
+export const assertSoldeerPackage = assertNameVersion(assertSoldeerName, assertSoldeerVersion)
 // As Cargo.lock and soldeer.lock write a checksum.
 export const assertSha256 = assertion('a sha256 in lowercase hex', matches(/^[\da-f]{64}$/u))

package/src/cache.js

@@ -3,10 +3,10 @@ import { constants } from 'node:fs'
 import { mkdir, open, rename, rm, writeFile } from 'node:fs/promises'
 import { dirname, join, resolve } from 'node:path'
 
-import { assertDirectoryPath } from './args.js'
+import { assertDirectoryPath, isRepo } from './args.js'
 import { MAX_BYTES, decode } from './http.js'
 
-const DIRS = new Set(['npm/repos', 'npm/tarballs', 'cargo/repos', 'cargo/crates', 'composer/repos', 'soldeer/zips', 'github/trees'])
+const DIRS = new Set(['npm/repos', 'npm/tarballs', 'cargo/repos', 'cargo/crates', 'composer/repos', 'soldeer/repos', 'soldeer/zips', 'github/trees'])
 const RECORD_TTL_MS = 30 * 24 * 60 * 60 * 1000 // A link only moves on a transfer or rename, and GitHub redirects those.
 
 let root
@@ -93,3 +93,21 @@ export async function readRecord(dir, name) {
 }
 
 export const writeRecord = (dir, name, value) => writeCacheJSON(dir, `${name}.json`, { at: Date.now(), name, ...value })
+
+// Name → the GitHub repo cached for it, for those of `names` that have one.
+export async function readRepos(dir, names) {
+  const repos = new Map()
+  for (const name of names) {
+    const entry = await readRecord(dir, name)
+    if (isRepo(entry?.github)) repos.set(name, entry.github)
+  }
+  return repos
+}
+
+// An answer into `repos`, and into the cache where it found a repo.
+export async function addRepos(dir, repos, answer) {
+  for (const [name, github] of answer) {
+    repos.set(name, github)
+    if (github) await writeRecord(dir, name, { github })
+  }
+}

package/src/{cargo.js → cargo/crate.js}

@@ -3,16 +3,16 @@ import { readdir } from 'node:fs/promises'
 import { homedir } from 'node:os'
 import { join, resolve } from 'node:path'
 
-import { assertCrateName, assertCrateVersion, assertSha256, printable, show } from './args.js'
-import { verifiedDownload } from './download.js'
-import { CRATES_INDEX, CRATES_STATIC, buildUrl, encodeSegment, request } from './http.js'
+import { assertCrate, assertSha256, printable, show } from '../args.js'
+import { verifiedDownload } from '../download.js'
+import { CRATES_INDEX, CRATES_STATIC, buildUrl, encodeSegment, request } from '../http.js'
 
 const DIR = 'cargo/crates' // No expiry: crates.io never takes a version twice.
 
 // The sparse index, what cargo reads: a file per crate, by its lowercased
 // name under 1/, 2/, 3/<first letter>/ or <1st-2nd>/<3rd-4th>/, with a
 // JSON line per version, `cksum` the .crate's sha256.
-async function getChecksum(name, version) {
+async function getChecksum(method, name, version) {
   const lower = name.toLowerCase()
   const prefix = lower.length < 3 ? [String(lower.length)] : lower.length === 3 ? ['3', lower[0]] : [lower.slice(0, 2), lower.slice(2, 4)]
   const text = await request(buildUrl(CRATES_INDEX, [...prefix, lower]), { as: 'text' })
@@ -20,13 +20,13 @@ async function getChecksum(name, version) {
     try {
       return JSON.parse(line)
     } catch {
-      assert.fail(`getCrate: the index for ${name} has a line that is not JSON: ${printable(line.slice(0, 200))}`)
+      assert.fail(`${method}: the index for ${name} has a line that is not JSON: ${printable(line.slice(0, 200))}`)
     }
   }
   const entry = text.split('\n').filter(Boolean).map(parse).find((candidate) => candidate?.vers === version)
-  assert.ok(entry, `getCrate: the index has no ${name}@${version}`)
-  assert.ok(entry.name === name, `getCrate: the index answered for ${show(entry.name)}, not ${name}`)
-  assertSha256('getCrate', 'the index cksum', entry.cksum)
+  assert.ok(entry, `${method}: the index has no ${name}@${version}`)
+  assert.ok(entry.name === name, `${method}: the index answered for ${show(entry.name)}, not ${name}`)
+  assertSha256(method, 'the index cksum', entry.cksum)
   return entry.cksum
 }
 
@@ -37,11 +37,17 @@ async function localPaths(name, version) {
   return (await readdir(root).catch(() => [])).map((registry) => join(root, registry, `${name}-${version}.crate`))
 }
 
+export async function verifyChecksum(name, version, checksum) {
+  assertCrate('verifyChecksum', name, version)
+  assertSha256('verifyChecksum', 'checksum', checksum)
+  const cksum = await getChecksum('verifyChecksum', name, version)
+  assert.ok(cksum === checksum, `verifyChecksum: ${name}@${version} is ${cksum} on crates.io, not ${checksum}`)
+}
+
 export async function getCrate(name, version, checksum) {
-  assertCrateName('getCrate', 'name', name)
-  assertCrateVersion('getCrate', 'version', version)
+  assertCrate('getCrate', name, version)
   if (checksum !== undefined) assertSha256('getCrate', 'checksum', checksum)
-  const expected = checksum ?? await getChecksum(name, version)
+  const expected = checksum ?? await getChecksum('getCrate', name, version)
   const locate = () => buildUrl(CRATES_STATIC, ['crates', name, `${name}-${encodeSegment(version)}.crate`])
   return await verifiedDownload({ method: 'getCrate', dir: DIR, what: `${name}@${version}`, ext: 'crate', algorithm: 'sha256', expected, local: await localPaths(name, version), locate })
 }

package/src/cargo/repos.js

@@ -0,0 +1,52 @@
+import assert from 'node:assert/strict'
+import { setTimeout as sleep } from 'node:timers/promises'
+
+import { assertCrateName, assertNames, show } from '../args.js'
+import { addRepos, readRepos } from '../cache.js'
+import { CRATES_API, buildUrl, request } from '../http.js'
+import { chunks } from '../pool.js'
+import { githubRepoOfUrl } from '../remote.js'
+
+const DIR = 'cargo/repos'
+const PER_REQUEST = 100
+const PACE_MS = 1000 // crates.io asks for a request a second at most, and a user agent.
+const USER_AGENT = '@preventive/upstream (https://github.com/PreventiveMeasures/libraries)'
+
+// One request for up to a hundred crates: each name → the GitHub repo its
+// `repository` names, or null where it names none. A crate crates.io
+// leaves out of its answer is one it does not have, null too.
+async function askCrates(method, names) {
+  const url = buildUrl(CRATES_API, ['api', 'v1', 'crates'], { 'ids[]': names, per_page: PER_REQUEST })
+  const answer = await request(url, { as: 'json', headers: { 'User-Agent': USER_AGENT } })
+  assert.ok(Array.isArray(answer?.crates), `${method}: expected a list of crates from crates.io`)
+  const found = new Map(names.map((name) => [name, null]))
+  for (const crate of answer.crates) {
+    assert.ok(names.includes(crate?.id), `${method}: crates.io answered for ${show(crate?.id)}, which was not asked`)
+    found.set(crate.id, githubRepoOfUrl(crate.repository) ?? null)
+  }
+  return found
+}
+
+// Name → its GitHub repo, or null where crates.io has no such crate or it
+// names no GitHub repo, through the cache: only a repo found is cached,
+// for a month. A failed request throws, or with `soft` leaves its names
+// out; `cachedOnly` asks nothing.
+export async function lookUpCrateRepos(method, names, { soft = false, cachedOnly = false } = {}) {
+  const repos = await readRepos(DIR, names)
+  if (cachedOnly) return repos
+  for (const [i, chunk] of chunks(names.filter((name) => !repos.has(name)), PER_REQUEST).entries()) {
+    if (i > 0) await sleep(PACE_MS)
+    const answer = await askCrates(method, chunk).catch((error) => {
+      if (soft) return new Map()
+      throw error
+    })
+    await addRepos(DIR, repos, answer)
+  }
+  return repos
+}
+
+export async function resolveCrateRepos(crateNames, options = {}) {
+  const names = assertNames('resolveCrateRepos', 'crateNames', crateNames, options, assertCrateName)
+  const repos = await lookUpCrateRepos('resolveCrateRepos', names, { soft: true, cachedOnly: options.cachedOnly })
+  return new Map(names.flatMap((name) => (repos.get(name) ? [[name, { github: repos.get(name) }]] : [])))
+}

package/src/github/read.js

@@ -1,11 +1,10 @@
 import assert from 'node:assert/strict'
 import { Buffer } from 'node:buffer'
-import { createHash } from 'node:crypto'
 
-import { assertArgs, assertGhsa, assertLogin, assertNumber, assertPath, assertRef, assertRepo, assertSha, assertTreeId, isSha, isSha1, optional, sameName, show } from '../args.js'
+import { assertArgs, assertGhsa, assertLogin, assertNumber, assertPath, assertRef, assertRepo, assertSha, assertTagName, assertTreeId, isSha, isSha1, isTagName, optional, sameName, show } from '../args.js'
 import { verifiedDownload } from '../download.js'
-import { decode, encodeSegment } from '../http.js'
-import { gitTreeOfListing } from '../tree.js'
+import { decode, encodeSegment, requestWithHeaders } from '../http.js'
+import { gitTreeOfListing, objectId } from '../tree.js'
 import { api, bindMethods, call, clientHeaders, isGone, repoApi } from './client.js'
 
 const PER_PAGE = 100
@@ -22,6 +21,24 @@ async function* pages(method, headers, pageUrl, maxPages = MAX_PAGES) {
   }
 }
 
+// A list GitHub pages by a cursor instead: the `after` of each page's
+// Link header `next` link, the one thing read off the link, so the next
+// page is asked of the list `pageUrl` names, wherever the link points. A
+// next link proves a page more.
+async function* cursorPages(method, headers, pageUrl, maxPages = MAX_PAGES) {
+  const paging = { per_page: PER_PAGE }
+  for (let page = 1; ; page++) {
+    const answer = await requestWithHeaders(pageUrl(paging), { as: 'json', headers })
+    assert.ok(Array.isArray(answer.body), `${method}: expected an array for page ${page}`)
+    yield answer.body
+    const next = /<([^>]*)>\s*;\s*rel="next"/u.exec(answer.headers.get('link') ?? '')?.[1]
+    if (next === undefined) return
+    paging.after = URL.parse(next)?.searchParams.get('after')
+    assert.ok(paging.after, `${method}: page ${page} links the next with no cursor`)
+    assert.ok(page < maxPages, `${method}: more than ${maxPages} pages`)
+  }
+}
+
 const paginate = async (...args) => (await Array.fromAsync(pages(...args))).flat()
 const getCurrentUser = (headers) => call(headers, api(['user']))
 
@@ -48,6 +65,32 @@ export async function getRepoHead(headers, options) {
   return { branch: ref, oid: data.object.sha }
 }
 
+async function getRepoTag(headers, options) {
+  assertArgs('getRepoTag', options, { repo: assertRepo, tag: assertTagName })
+  const { repo, tag } = options
+  const ref = await call(headers, repoApi(repo, ['git', 'ref', 'tags', encodeSegment(tag)]))
+  assert.ok(ref?.ref === `refs/tags/${tag}`, `getRepoTag: GitHub answered for ${show(ref?.ref)}, not ${show(`refs/tags/${tag}`)}`)
+  let { object } = ref
+  for (let hops = 0; object?.type === 'tag' && isSha(object.sha) && hops < 8; hops++) {
+    const annotated = await call(headers, repoApi(repo, ['git', 'tags', object.sha]))
+    assert.ok(annotated?.sha === object.sha, `getRepoTag: GitHub answered for another tag object than ${object.sha}`)
+    object = annotated.object
+  }
+  assert.ok(object?.type === 'commit' && isSha(object.sha), `getRepoTag: ${repo} has no commit for tag ${show(tag)}`)
+  return { tag, oid: object.sha }
+}
+
+// GitHub lists each tag with the commit it names, an annotated one's too.
+async function listRepoTags(headers, options) {
+  assertArgs('listRepoTags', options, { repo: assertRepo, maxPages: optional(assertNumber) })
+  const { repo, maxPages } = options
+  const tags = await paginate('listRepoTags', headers, (paging) => repoApi(repo, ['tags'], paging), maxPages)
+  return tags.map((entry) => {
+    assert.ok(isTagName(entry?.name) && isSha(entry.commit?.sha), `listRepoTags: GitHub listed ${show(entry?.name)} in ${repo}, which is no tag name with a commit`)
+    return { tag: entry.name, oid: entry.commit.sha }
+  })
+}
+
 // GitHub's object for the path first: a directory, symlink or submodule is
 // refused rather than read as a file's text. Up to 1 MB the object holds
 // the content; past it, `encoding: none`, and the blob it names is read,
@@ -63,7 +106,7 @@ async function getRepoFile(headers, options) {
   const bytes = file.encoding === 'none'
     ? await call({ ...headers, Accept: 'application/vnd.github.raw' }, repoApi(repo, ['git', 'blobs', file.sha]), { as: 'bytes' })
     : Buffer.from(file.content, 'base64')
-  const blob = createHash('sha1').update(`blob ${bytes.length}\0`).update(bytes).digest('hex')
+  const blob = objectId('blob', bytes).toString('hex')
   assert.ok(bytes.length === file.size && blob === file.sha, `getRepoFile: ${show(path)} came back as blob ${blob}, not ${file.sha}`)
   return decode(bytes, url)
 }
@@ -113,12 +156,13 @@ async function listTree(method, headers, repo, tree) {
 }
 
 async function treeAt(method, headers, options) {
-  assertArgs(method, options, { repo: assertRepo, sha: assertSha, path: optional(assertPath) })
-  const { repo, sha, path } = options
+  assertArgs(method, options, { repo: assertRepo, sha: assertSha, directory: optional(assertPath), path: optional(assertPath) })
+  assert.ok(options.directory === undefined || options.path === undefined, `${method}: directory and path are one option, pass directory alone`)
+  const { repo, sha, directory = options.path } = options
   let tree = await commitTree(method, headers, repo, sha)
-  for (const name of path?.split('/') ?? []) {
+  for (const name of directory?.split('/') ?? []) {
     const entry = (await listTree(method, headers, repo, tree)).find((candidate) => candidate.path === name)
-    assert.ok(entry?.type === 'tree', `${method}: ${repo}@${sha} has no directory at ${show(path)}`)
+    assert.ok(entry?.type === 'tree', `${method}: ${repo}@${sha} has no directory at ${show(directory)}`)
     tree = entry.sha
   }
   return tree
@@ -168,15 +212,12 @@ async function getAdvisory(headers, options) {
   return advisory
 }
 
-// One page: GitHub pages this list by a cursor in the Link header, which
-// `call` does not read, so a full page is refused rather than cut short.
 async function listRepoAdvisories(headers, options) {
   assertArgs('listRepoAdvisories', options, { repo: assertRepo })
-  const list = await call(headers, repoApi(options.repo, ['security-advisories'], { state: 'published', per_page: PER_PAGE }))
-  assert.ok(Array.isArray(list), `listRepoAdvisories: expected an array for ${options.repo}`)
-  assert.ok(list.length < PER_PAGE, `listRepoAdvisories: ${options.repo} has ${PER_PAGE} or more published advisories, more than a page`)
-  return list
+  const { repo } = options
+  const pageUrl = (paging) => repoApi(repo, ['security-advisories'], { state: 'published', ...paging })
+  return (await Array.fromAsync(cursorPages('listRepoAdvisories', headers, pageUrl))).flat()
 }
 
-export const readMethods = { getCurrentUser, listUserRepos, getRepo, getRepoHead, getRepoFile, getRepoTarball, getRepoTreeTarball, getRepoTreeId, listRepoDir, getPullRequest, getCollaboratorPermission, getAdvisory, listRepoAdvisories }
+export const readMethods = { getCurrentUser, listUserRepos, getRepo, getRepoHead, getRepoTag, listRepoTags, getRepoFile, getRepoTarball, getRepoTreeTarball, getRepoTreeId, listRepoDir, getPullRequest, getCollaboratorPermission, getAdvisory, listRepoAdvisories }
 export const createClient = (options) => bindMethods(clientHeaders('createClient', options, true), readMethods)

package/src/http.js

@@ -101,22 +101,27 @@ export async function readBody(res, limit, { truncate = false } = {}) {
   return new Uint8Array(await new Blob(chunks).arrayBuffer(), 0, Math.min(size, limit))
 }
 
+function parse(bytes, url, as) {
+  if (as === 'bytes') return bytes
+  const text = decode(bytes, url)
+  if (as === 'text') return text
+  try {
+    return JSON.parse(text)
+  } catch (cause) {
+    throw new Error(`Malformed JSON from ${url}: ${printable(text.slice(0, 200))}`, { cause })
+  }
+}
+
 // Read as the caller says, not by content type, which proxies drop or
-// rewrite.
-export async function request(url, options) {
+// rewrite; answered with the response's headers.
+export async function requestWithHeaders(url, options) {
   const res = await send(url, options)
   if (!res.ok) {
     // A stream decode holds back a character cut at the limit rather than refusing it.
     const text = await readBody(res, 4096, { truncate: true }).then((bytes) => new TextDecoder('utf-8', { fatal: true }).decode(bytes, { stream: true })).catch(() => '')
     throw new HttpError(res.status, `${options.method ?? 'GET'} ${url} ${res.status}: ${printable(text)}`)
   }
-  const bytes = await readBody(res, LIMITS[options.as].bytes)
-  if (options.as === 'bytes') return bytes
-  const text = decode(bytes, url)
-  if (options.as === 'text') return text
-  try {
-    return JSON.parse(text)
-  } catch (cause) {
-    throw new Error(`Malformed JSON from ${url}: ${printable(text.slice(0, 200))}`, { cause })
-  }
+  return { body: parse(await readBody(res, LIMITS[options.as].bytes), url, options.as), headers: res.headers }
 }
+
+export const request = async (url, options) => (await requestWithHeaders(url, options)).body

package/src/npm/repos.js

@@ -1,6 +1,6 @@
 import assert from 'node:assert/strict'
 
-import { assertArgs, assertBoolean, assertPackageName, assertRepo, isRepo, optional, show } from '../args.js'
+import { assertNames, assertPackageName, assertRepo, isRepo, show } from '../args.js'
 import { readRecord, writeRecord } from '../cache.js'
 import { NPM_REGISTRY, buildUrl, isNotFound, recover, request } from '../http.js'
 import { assertRepoDirectory, getRepo, isRepoDirectory } from '../package.js'
@@ -42,10 +42,7 @@ export async function writePackageRepoCache(name, github, directory = '') {
 }
 
 export async function resolvePackageRepos(packageNames, options = {}) {
-  assert.ok(typeof packageNames?.[Symbol.iterator] === 'function' && typeof packageNames !== 'string', 'resolvePackageRepos: packageNames must be an iterable of names')
-  assertArgs('resolvePackageRepos', options, { cachedOnly: optional(assertBoolean) })
-  const names = [...new Set(packageNames)]
-  for (const name of names) assertPackageName('resolvePackageRepos', 'name', name)
+  const names = assertNames('resolvePackageRepos', 'packageNames', packageNames, options, assertPackageName)
   const found = await pool(names, CONCURRENCY, (name) => (options.cachedOnly ? readPackageRepoCache(name) : lookUpPackageRepo(name)).catch(() => null))
   return new Map(names.flatMap((name, i) => (found[i] ? [[name, found[i]]] : [])))
 }

package/src/npm/tarball.js

@@ -3,7 +3,7 @@ import { Buffer } from 'node:buffer'
 import { homedir } from 'node:os'
 import { join, resolve } from 'node:path'
 
-import { assertArgs, assertPackageName, assertPackageVersion, assertion, matches, show } from '../args.js'
+import { assertArgs, assertPackage, assertion, matches, show } from '../args.js'
 import { verifiedDownload } from '../download.js'
 import { NPM_REGISTRY, buildUrl, request } from '../http.js'
 
@@ -13,11 +13,6 @@ const DIR = 'npm/tarballs' // No expiry: the registry never takes a version twic
 // 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))
 
-function assertPackage(method, name, version) {
-  assertPackageName(method, 'name', name)
-  assertPackageVersion(method, 'version', version)
-}
-
 // `{ 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:

package/src/semver-peer.cjs

@@ -0,0 +1,8 @@
+'use strict'
+
+// The semver peer dependency by a plain require(), which a bundler follows
+// and bundles: CommonJS for that alone. In an ESM bundle that leaves semver
+// out, this require() is the bundler's stub, which throws.
+module.exports = function requirePeer() {
+  return require('semver')
+}