@preventive/upstream 1.0.0 → 1.1.0

package/advisories.d.ts

@@ -1,6 +1,3 @@
-// Hand-written against advisories.js; a change to either belongs with the
-// other.
-
 import type { Client, RepoName } from './github.js'
 import type { CacheStore } from './npm.js'
 
@@ -53,6 +50,15 @@ export interface AdvisoryOptions {
   // and its rows take OSV's record of their GHSA, one more request each
   // (no GitHub client needed).
   details?: boolean
+  // Also asks OSV of each npm package's versions, as cargo and composer
+  // packages always are, for what the registry does not have: above all
+  // the malicious packages' records (MAL-...), which it has none of, as
+  // those of npm releases taken down that GitHub's database has no
+  // advisory of. A version a registry row reports under the same advisory,
+  // its id among an OSV record's id and aliases, is left to that row,
+  // which takes the record's ids among its aliases. Sends each npm
+  // package's name and versions to OSV, so not for a private package.
+  osv?: boolean
 }
 
 // One advisory on one package, with the versions asked about that it
@@ -61,11 +67,13 @@ export interface Advisory {
   ecosystem: Ecosystem
   name: string
   // `registry`: npm's, as `npm audit` has it, one row per vulnerable
-  // range. `osv`: OSV's records for cargo and composer, RustSec's, GitHub's
-  // and malicious packages' (MAL-...) among them; of the records naming each
-  // other as aliases, directly or through others, a version is reported
-  // under one only: RustSec's, else the GHSA, else the first by id. Each
-  // has the others' ids among its aliases.
+  // range. `osv`: OSV's records for cargo and composer, and with `osv` for
+  // npm, the versions they cover that no registry row reports under the
+  // same advisory; RustSec's, GitHub's and malicious packages' (MAL-...)
+  // among them; of the records naming each other as aliases, directly or
+  // through others, a version is reported under one only: RustSec's, else
+  // the GHSA, else the first by id. Each has the others' ids among its
+  // aliases.
   // `repository`: published on the package's repository, one row per
   // range, holding only the versions the others' answer does not report
   // under that GHSA. The only source for `soldeer` and `github`, where
@@ -84,6 +92,8 @@ export interface Advisory {
   // (https://osv.dev/vulnerability/RUSTSEC-...). Built, never fetched: only
   // a registry row without a GHSA (npm:<id>) has none.
   url?: string
+  // The advisory's other ids: an `osv` row's record's own and its group's,
+  // and with `osv`, a registry row's OSV records' of it.
   aliases: string[]
   title?: string
   // With `details`, the advisory's full text, Markdown as published: an
@@ -113,14 +123,18 @@ export interface Advisory {
 // merged, and must not name two repositories. npm is asked 250 names a
 // request, OSV 1000 versions, Soldeer one project, and with `details`, OSV
 // one GHSA among npm's rows; a project Soldeer does not have or that names
-// no GitHub repository, and a repository gone, renamed or blocked, add
-// nothing, and a GHSA OSV does not have adds no `details`. Any other
-// failure, a malformed answer, or one about something not asked, throws:
-// nothing is left out quietly.
+// no GitHub repository, a repository gone or blocked, and one GitHub
+// redirects anywhere but to a repository by its id, add nothing, and a
+// GHSA OSV does not have adds no `details`. A repository renamed or
+// transferred, which GitHub redirects to it by its id, is listed by the
+// name it has now, as getRepo's `followRedirect` (github.js) finds it, its
+// rows' `url` on it. Any other failure, a malformed answer, or one about
+// something not asked, throws: nothing is left out quietly.
 // A repository's listing is kept for 90 minutes, as one entry for every
-// spelling of its name, holding only what rows are made from, `details`
-// included: in setCacheDir's cache gzipped, in a `cache` store as it is,
-// or with `cache` false, nowhere. 90 minutes is how late an advisory its
+// spelling of the name it is asked by, one renamed or transferred too,
+// holding only what rows are made from, `details` included: in
+// setCacheDir's cache gzipped, in a `cache` store as it is, or with
+// `cache` false, nowhere. 90 minutes is how late an advisory its
 // maintainer publishes can be seen. One gone or malformed is not kept.
 // Sorted by ecosystem and name. Versions are matched by npm's semver, from
 // the npm beside node, or by the semver peer where there is no npm.

package/cargo.d.ts

@@ -1,5 +1,3 @@
-// Hand-written against cargo.js; a change to either belongs with the other.
-//
 // A name is asserted to be a crate name, a version an exact semver
 // version, and a checksum 64 lowercase hex digits, before any request or
 // cache path. The cache is setCacheDir's (npm.js).

package/git.d.ts

@@ -1,5 +1,3 @@
-// Hand-written against git.js; a change to either belongs with the other.
-
 // The shape getRepo (package.js) answers in, and HEAD's commit. Each
 // field best-effort: left out where it cannot be read.
 export interface GitCheckout {

package/github/write.d.ts

@@ -1,5 +1,4 @@
-// Hand-written against github/write.js; a change to either belongs with
-// the other. Arguments are checked as github.d.ts describes.
+// Arguments are checked as github.d.ts describes.
 
 import type { Client, RepoName } from '../github.js'
 

package/github.d.ts

@@ -1,5 +1,3 @@
-// Hand-written against github.js; a change to either belongs with the other.
-//
 // Every method checks its arguments hard before any request is built: an
 // options object holding only the keys listed here, a repo that is
 // `owner/name` by GitHub's rules, branches and tags that git would take,
@@ -7,11 +5,12 @@
 // component, titles and headlines on one line. A bad one is a rejection
 // naming the method; nothing is sent. Every URL is built from checked,
 // encoded segments and has to come back out of URL parsing unchanged.
-// Redirects are refused, except the tarballs', so an answer is about the
-// repo asked for. A response is read up to a size limit (64 MiB of JSON,
-// 128 MiB of a file, 512 MiB of a tarball) and within a timeout (30
-// seconds, 5 minutes for a tarball), and what it says goes into an error
-// message escaped.
+// Redirects are refused, so an answer is about the repo asked for, except
+// the tarballs' and, where asked, getRepo's for a repo renamed or
+// transferred. A response is read up to a size limit (64 MiB of JSON, 128
+// MiB of a file, 512 MiB of a tarball) and within a timeout (30 seconds, 5
+// minutes for a tarball), and what it says goes into an error message
+// escaped.
 
 // `owner/name`.
 export type RepoName = string
@@ -35,14 +34,62 @@ export interface RepoDirEntry {
   sha: string
 }
 
-// A failed request: `status` is the HTTP status GitHub answered with.
+// A lockfile's format, by the tool that writes it, with the names it
+// writes one under and those of the project files it locks as
+// src/lockfiles.js lists them. Those @preventive/lockfile reads are as it
+// names the modules that do, yarn as yarn1.js, which reads Yarn 1's alone:
+// only the text tells a later Yarn's apart.
+export type LockfileFormat =
+  | 'pnpm' | 'npm' | 'yarn' | 'bun' | 'deno'
+  | 'uv' | 'poetry' | 'pylock' | 'pipenv' | 'pdm' | 'pixi' | 'conda-lock'
+  | 'bundler' | 'composer' | 'cargo' | 'soldeer' | 'foundry'
+  | 'cocoapods' | 'swiftpm' | 'carthage'
+  | 'go' | 'dep' | 'nuget' | 'paket' | 'gradle' | 'pub' | 'mix' | 'rebar' | 'julia'
+  | 'stack' | 'cabal' | 'shards' | 'opam' | 'nix' | 'conan' | 'bazel' | 'helm' | 'renv' | 'terraform'
+
+// A file by a lockfile's name: `path` from the repo's root, as getRepoFile
+// takes it, and `sha` its blob's id.
+export interface RepoLockfile {
+  path: string
+  format: LockfileFormat
+  sha: string
+}
+
+// A file by a project file's name, as RepoLockfile is, and the formats of
+// the lockfiles that may lock its project, in src/lockfiles.js' order:
+// whether one does, and where, is the tool's to say, a workspace's at its
+// root.
+export interface RepoProjectFile {
+  path: string
+  formats: LockfileFormat[]
+  sha: string
+}
+
+// A failed request: `status` is the HTTP status GitHub answered with, and
+// `headers` its response's (a redirect's `location` among them), on every
+// call but a GraphQL one (github/write.js).
 export class HttpError extends Error {
   name: 'HttpError'
   status: number
+  headers?: Headers
 }
 
 // Reads only.
 export interface Client {
+  // Every file by a lockfile's name, and every project file of a tool that
+  // writes one, in the full commit `sha`, or under its `directory`, found as
+  // getRepoTreeId finds it, each list sorted by path; and a project file no
+  // name tells, by a lockfile beside it named after it: a Python script
+  // `uv lock --script` locked, or a Stack or Cabal project file of another
+  // name than stack.yaml or cabal.project. From one listing of the tree
+  // with every tree under it, each hashed back to its id, so none is left
+  // out or changed; where GitHub cuts that short, as it does past 100,000
+  // entries, from the tree's own listing and then each subtree's in turn.
+  // Not looked in: a submodule, which is another repo's commit, or a
+  // `node_modules`, of packages installed. A symlink is no file. Refused
+  // where a path found is one getRepoFile does not take, such as one with a
+  // control character in it.
+  findRepoLockfiles(options: { repo: RepoName; sha: string; directory?: string }): Promise<{ lockfiles: RepoLockfile[]; projects: RepoProjectFile[] }>
   // An advisory by its GHSA id. With `repo`, that repository's published
   // copy: the maintainer's latest text, there before GitHub reviews it,
   // and shaped as a repository advisory (`state`, `patched_versions`, no
@@ -58,7 +105,14 @@ export interface Client {
   // Refused unless GitHub answers with that pull request in that repo.
   getPullRequest(options: { repo: RepoName; number: number }): Promise<{ title: string; status: PullRequestStatus }>
   // GitHub's repository object, refused unless it is the repo asked for.
-  getRepo(options: { repo: RepoName }): Promise<any>
+  // With `followRedirect`, a repository renamed or transferred, which GitHub
+  // answers with a redirect to it by its id
+  // (`https://api.github.com/repositories/<id>`), is asked for there, with
+  // the same token, once: the repository as it is now, refused unless it
+  // has that id and a `full_name` that is `owner/name`, the name to ask its
+  // other calls with. A redirect anywhere else, or a second, is refused as
+  // without it: an HttpError with the redirect's status.
+  getRepo(options: { repo: RepoName; followRedirect?: boolean }): Promise<any>
   // A file's contents as text, at `ref` or the default branch. Refused for
   // a directory, a symlink or a submodule, unless the bytes hash to the
   // blob GitHub names for the path, and unless valid UTF-8.

package/npm.d.ts

@@ -1,5 +1,3 @@
-// Hand-written against npm.js; a change to either belongs with the other.
-//
 // Every call that reaches the registry first asserts that the name is a
 // string of the shape npm takes, and a version a string that npm's
 // semver.valid answers with unchanged; neither goes near a request, or a
@@ -73,10 +71,12 @@ export interface CacheOptions {
 }
 
 // A failed request: `status` is the HTTP status the registry answered
-// with (404 for a package or version it does not have).
+// with (404 for a package or version it does not have), and `headers` its
+// response's.
 export class HttpError extends Error {
   name: 'HttpError'
   status: number
+  headers?: Headers
 }
 
 // A package's GitHub repo as its registry metadata names it -- getRepo

package/package.d.ts

@@ -1,5 +1,3 @@
-// Hand-written against package.js; a change to either belongs with the other.
-
 export interface PackageRepoLink {
   // `owner/name`, by GitHub's own rules.
   github?: string

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@preventive/upstream",
-  "version": "1.0.0",
-  "description": "Minimal npm, crates.io and Soldeer registry clients, a GitHub client, and a git checkout reader: the calls we use, nothing more",
+  "version": "1.1.0",
+  "description": "Minimal npm, crates.io, Soldeer, GitHub and git checkout clients",
   "type": "module",
   "exports": {
     "./advisories.js": {
@@ -85,6 +85,7 @@
     "src/github/read.js",
     "src/github/write.js",
     "src/http.js",
+    "src/lockfiles.js",
     "src/npm/cacache.js",
     "src/npm/registry.js",
     "src/npm/repos.js",

package/semver.d.ts

@@ -1,5 +1,3 @@
-// Hand-written against semver.js; a change to either belongs with the other.
-
 // npm's own semver, borrowed from the npm beside node and passed through
 // as it is; where there is no npm, the `semver` package, an optional peer
 // dependency. Without either, every call throws, except valid() on a plain

package/soldeer.d.ts

@@ -1,6 +1,3 @@
-// Hand-written against soldeer.js; a change to either belongs with the
-// other.
-//
 // The name is asserted to be one Soldeer takes, the version a string of
 // letters, digits, `.`, `_`, `+` and `-`, and the checksum 64 lowercase hex
 // digits, before any request or cache path. The cache is setCacheDir's

package/src/advisories/github.js

@@ -1,9 +1,9 @@
 import assert from 'node:assert/strict'
 
-import { assertRepo, assertSoldeerName, assertSoldeerVersion, assertion, isGhsa, isRefName, isStrings } from '../args.js'
+import { assertRepo, assertSoldeerName, assertSoldeerVersion, assertion, isGhsa, isRefName, isRepo, isStrings } from '../args.js'
 import { readRecord, writeRecord } from '../cache.js'
 import { isGone } from '../github/client.js'
-import { recover } from '../http.js'
+import { HttpError, recover } from '../http.js'
 import { pool } from '../pool.js'
 import { isExactVersion } from '../semver.js'
 import { advisoryUrl, covered, detailsOf, isText, mayBeInRange, metrics } from './common.js'
@@ -21,7 +21,7 @@ const isRepoAdvisory = (advisory) => advisory && typeof advisory === 'object' &&
   && advisory.state === 'published' && isText(advisory.summary)
   && (advisory.vulnerabilities == null || Array.isArray(advisory.vulnerabilities)) && (advisory.cwe_ids == null || isStrings(advisory.cwe_ids))
 
-export const assertClient = assertion('a GitHub client from createClient', (value) => typeof value?.listRepoAdvisories === 'function')
+export const assertClient = assertion('a GitHub client from createClient', (value) => typeof value?.listRepoAdvisories === 'function' && typeof value.getRepo === 'function')
 
 // A maintainer may give a vulnerable range only its lower bound, and the
 // version that fixed it apart (`>= 5.0.0-beta.1`, patched in `5.0.0-rc.2`),
@@ -67,18 +67,37 @@ const isDigest = (advisory) => advisory && typeof advisory === 'object' && isGhs
   && (advisory.description === undefined || isText(advisory.description))
   && Array.isArray(advisory.ranges) && advisory.ranges.every((entry) => typeof entry?.range === 'string')
 
-// A repository's listing, digested, through the cache: GitHub's names are
-// case-insensitive, so one entry answers every spelling. A repository gone,
-// renamed or blocked has none, and that is not kept.
+// GitHub answers for a repository renamed or transferred with a redirect,
+// which getRepo follows to the repository it is now, listed by that name.
+const isRedirect = (err) => err instanceof HttpError && err.status >= 300 && err.status < 400
+
+async function listingOf(github, repo) {
+  try {
+    return { repo, list: await github.listRepoAdvisories({ repo }) }
+  } catch (err) {
+    if (!isRedirect(err)) throw err
+  }
+  const moved = (await github.getRepo({ repo, followRedirect: true })).full_name
+  return { repo: moved, list: await github.listRepoAdvisories({ repo: moved }) }
+}
+
+// A repository's listing, digested, through the cache, and the repository
+// it is of: GitHub's names are case-insensitive, so one entry answers every
+// spelling, and one renamed or transferred is kept under the name asked,
+// with `repo` the one it has now. A repository gone or blocked, or
+// redirected anywhere getRepo does not follow, has none, and that is not
+// kept.
 async function listAdvisories(github, repo, cache) {
   const name = repo.toLowerCase()
   const entry = await readRecord(DIR, name, cache, LISTING_TTL_MS)
-  if (entry?.v === VERSION && Array.isArray(entry.advisories) && entry.advisories.every(isDigest)) return entry.advisories
-  const list = await github.listRepoAdvisories({ repo }).catch(recover(isGone, null))
-  if (list === null) return []
-  const advisories = digest(repo, list)
-  if (advisories.every(isDigest)) await writeRecord(DIR, name, { v: VERSION, advisories }, cache)
-  return advisories
+  if (entry?.v === VERSION && (entry.repo === undefined || isRepo(entry.repo)) && Array.isArray(entry.advisories) && entry.advisories.every(isDigest)) {
+    return { repo: entry.repo ?? repo, advisories: entry.advisories }
+  }
+  const found = await listingOf(github, repo).catch(recover((err) => isGone(err) || isRedirect(err), null))
+  if (found === null) return { repo, advisories: [] }
+  const advisories = digest(found.repo, found.list)
+  if (advisories.every(isDigest)) await writeRecord(DIR, name, { v: VERSION, ...(found.repo !== repo && { repo: found.repo }), advisories }, cache)
+  return { repo: found.repo, advisories }
 }
 
 // GitHub's `>= 1.0.0, < 1.2.6` is npm's with the commas dropped.
@@ -109,10 +128,10 @@ function fromRepository(repo, name, advisory, range, asked, { covers, details })
 async function repositoryAdvisories(github, asked, { repoOf, takes = () => true, covers, details, cache }) {
   // GitHub's names are case-insensitive: one spelling asks for all.
   const namesOf = Map.groupBy([...asked.keys()].filter(repoOf), (name) => repoOf(name).toLowerCase())
-  const listed = await pool([...namesOf.values()], REPOS_AT_ONCE, async (names) => ({ repo: repoOf(names[0]), names, list: await listAdvisories(github, repoOf(names[0]), cache) }))
+  const listed = await pool([...namesOf.values()], REPOS_AT_ONCE, async (names) => ({ names, ...(await listAdvisories(github, repoOf(names[0]), cache)) }))
   const rows = new Map()
-  for (const { repo, names, list } of listed) {
-    for (const advisory of list) {
+  for (const { repo, names, advisories } of listed) {
+    for (const advisory of advisories) {
       for (const { range, ...pkg } of advisory.ranges) {
         for (const name of names.filter((candidate) => takes(candidate, pkg))) {
           rows.set(`${name} ${advisory.ghsa} ${range}`, fromRepository(repo, name, advisory, range, asked.get(name), { covers, details }))

package/src/advisories/index.js

@@ -35,7 +35,7 @@ function collect(packages) {
 }
 
 export async function advisories(packages, options = {}) {
-  assertArgs('advisories', options, { github: optional(assertClient), repoAdvisories: optional(assertBoolean), details: optional(assertBoolean), cache: optional(assertCache) })
+  assertArgs('advisories', options, { github: optional(assertClient), repoAdvisories: optional(assertBoolean), details: optional(assertBoolean), osv: optional(assertBoolean), cache: optional(assertCache) })
   assert.ok(!options.repoAdvisories || options.github, 'advisories: repoAdvisories needs a github client')
   const byEcosystem = collect(packages)
   for (const ecosystem of byEcosystem.keys()) assert.ok(!ECOSYSTEMS[ecosystem].repositoryOnly || options.github, `advisories: ${ecosystem} packages need a github client`)
@@ -44,7 +44,7 @@ export async function advisories(packages, options = {}) {
     const names = [...named.keys()].toSorted()
     const asked = new Map(names.map((name) => [name, [...named.get(name).versions].toSorted(compare)]))
     const known = new Map(names.filter((name) => named.get(name).github).map((name) => [name, named.get(name).github]))
-    const rows = await find(asked, { github: options.github, repoAdvisories: options.repoAdvisories === true, details: options.details === true, known, cache: options.cache })
+    const rows = await find(asked, { github: options.github, repoAdvisories: options.repoAdvisories === true, details: options.details === true, osv: options.osv === true, known, cache: options.cache })
     return rows.map((row) => ({ ecosystem, ...row }))
   }))
   return found.flat().filter((row) => row.versions.length > 0).toSorted((a, b) => order(a.ecosystem, b.ecosystem) || order(a.name, b.name))

package/src/advisories/npm.js

@@ -6,7 +6,7 @@ import { chunks, pool } from '../pool.js'
 import { compareVersions } from '../semver.js'
 import { advisoryUrl, covered, detailsOf, isText, metrics } from './common.js'
 import { withRepositories } from './github.js'
-import { RECORDS_AT_ONCE, getVuln } from './osv.js'
+import { RECORDS_AT_ONCE, getVuln, osvRows } from './osv.js'
 import { npmRepos } from './repos.js'
 
 const BULK_URL = buildUrl(NPM_REGISTRY, ['-', 'npm', 'v1', 'security', 'advisories', 'bulk'])
@@ -52,21 +52,48 @@ async function registryAdvisories(asked) {
 
 // The registry's rows carry no text: each GHSA's is OSV's record of it,
 // GitHub's advisory database as published, asked once for the rows that
-// cover an asked version. One OSV does not have yet has none.
+// cover an asked version, but where `osv` already read it. One OSV does
+// not have yet has none.
 async function withDetails(rows) {
-  const ghsas = [...new Set(rows.filter((row) => row.ghsa && row.versions.length > 0).map((row) => row.ghsa))]
+  const asks = (row) => row.source === 'registry' && row.details === undefined
+  const ghsas = [...new Set(rows.filter((row) => asks(row) && row.ghsa && row.versions.length > 0).map((row) => row.ghsa))]
   const records = await pool(ghsas, RECORDS_AT_ONCE, (ghsa) => getVuln(ghsa).catch(recover(isNotFound, undefined)))
   const text = new Map(ghsas.map((ghsa, i) => [ghsa, records[i]?.details]))
-  return rows.map((row) => ({ ...row, ...detailsOf(text.get(row.ghsa), row.ghsa) }))
+  return rows.map((row) => (asks(row) ? { ...row, ...detailsOf(text.get(row.ghsa), row.ghsa) } : row))
 }
 
-// What `npm audit` asks the registry, one row per vulnerable range.
+// With `osv`, OSV's records of the asked versions besides the registry's
+// rows, the malicious packages' (MAL-...), which the registry has none
+// of, among them. A version a registry row reports under the same
+// advisory, the row's id one of an OSV row's ids or aliases, is left to
+// that row, which takes the OSV row's ids among its aliases, and its text
+// where it is the same record; an OSV row keeps the versions no such row
+// reports.
+function withOsv(registry, osv) {
+  const rows = registry.map((row) => ({ ...row }))
+  const added = []
+  for (const record of osv) {
+    const ids = [record.id, ...record.aliases]
+    const same = rows.filter((row) => row.name === record.name && ids.includes(row.id) && row.versions.some((version) => record.versions.includes(version)))
+    for (const row of same) {
+      row.aliases = [...new Set([...row.aliases, ...ids])].filter((id) => id !== row.id)
+      if (record.id === row.id && record.details !== undefined) row.details = record.details
+    }
+    const versions = record.versions.filter((version) => !same.some((row) => row.versions.includes(version)))
+    if (versions.length > 0) added.push({ ...record, versions })
+  }
+  return [...rows, ...added]
+}
+
+// What `npm audit` asks the registry, one row per vulnerable range, and
+// with `osv`, what OSV has besides.
 export const NPM = {
   assertName: assertPackageName,
   assertVersion: assertPackageVersion,
   compare: compareVersions,
   advisories: async (asked, options) => {
-    const rows = await registryAdvisories(asked)
+    const [registry, osv] = await Promise.all([registryAdvisories(asked), options.osv ? osvRows({ osv: 'npm' }, asked, options) : []])
+    const rows = withOsv(registry, osv)
     return await withRepositories(options.details ? await withDetails(rows) : rows, asked, options, { ecosystem: 'npm', lookUp: npmRepos })
   },
 }

package/src/advisories/osv.js

@@ -84,9 +84,9 @@ function toAdvisory(ecosystem, name, versions, record, details) {
 // 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 } = ecosystem
+// each record has the others' ids as aliases. `osv` is OSV's name for the
+// ecosystem.
+export async function osvRows({ osv }, asked, { details }) {
   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)) {
@@ -118,9 +118,14 @@ async function osvAdvisories(ecosystem, asked, options) {
     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)) {
       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 }, options.details))
+      if (rest.length > 0) rows.push(toAdvisory(osv, name, rest, { ...record, aliases }, details))
     }
   }
   rows.sort((a, b) => order(a.name, b.name) || order(a.id, b.id))
-  return await withRepositories(rows, asked, options, { ecosystem: github, lookUp, covers })
+  return rows
+}
+
+async function osvAdvisories(ecosystem, asked, options) {
+  const { github, lookUp, covers } = ecosystem
+  return await withRepositories(await osvRows(ecosystem, asked, options), asked, options, { ecosystem: github, lookUp, covers })
 }

package/src/github/read.js

@@ -1,9 +1,10 @@
 import assert from 'node:assert/strict'
 import { Buffer } from 'node:buffer'
 
-import { assertArgs, assertGhsa, assertLogin, assertNumber, assertPath, assertRef, assertRepo, assertSha, assertTagName, assertTreeId, isSha, isSha1, isTagName, optional, sameName, show } from '../args.js'
+import { assertArgs, assertBoolean, assertGhsa, assertLogin, assertNumber, assertPath, assertRef, assertRepo, assertSha, assertTagName, assertTreeId, isRepo, isSha, isSha1, isTagName, optional, sameName, show } from '../args.js'
 import { verifiedDownload } from '../download.js'
-import { decode, encodeSegment, requestWithHeaders } from '../http.js'
+import { HttpError, decode, encodeSegment, requestWithHeaders } from '../http.js'
+import { FORMATS, lockfileOf, projectFormats } from '../lockfiles.js'
 import { gitTreeOfListing, objectId } from '../tree.js'
 import { api, bindMethods, call, clientHeaders, isGone, repoApi } from './client.js'
 
@@ -48,10 +49,29 @@ async function listUserRepos(headers, options) {
   return await paginate('listUserRepos', headers, (paging) => api(['user', 'repos'], { ...paging, sort: 'full_name' }), options?.maxPages)
 }
 
+// Where GitHub's API sends a repository renamed or transferred: to that
+// repository by its id.
+const REPO_BY_ID = /^https:\/\/api\.github\.com\/repositories\/([1-9]\d{0,14})$/u
+const REDIRECTS = new Set([301, 302, 307, 308])
+
+// With `followRedirect`, GitHub's redirect for a repository renamed or
+// transferred is followed, once, on its API alone, and the answer held to
+// the id it names rather than to the name asked; any other redirect, or a
+// second, is refused as without it.
 async function getRepo(headers, options) {
-  assertArgs('getRepo', options, { repo: assertRepo })
-  const info = await call(headers, repoApi(options.repo))
-  assert.ok(sameName(info?.full_name, options.repo), `getRepo: answered for ${show(info?.full_name)}, not ${options.repo}`)
+  assertArgs('getRepo', options, { repo: assertRepo, followRedirect: optional(assertBoolean) })
+  const { repo, followRedirect } = options
+  let info
+  try {
+    info = await call(headers, repoApi(repo))
+  } catch (err) {
+    const id = followRedirect && err instanceof HttpError && REDIRECTS.has(err.status) ? REPO_BY_ID.exec(err.headers.get('location') ?? '')?.[1] : undefined
+    if (id === undefined) throw err
+    const moved = await call(headers, api(['repositories', id]))
+    assert.ok(moved?.id === Number(id) && isRepo(moved.full_name), `getRepo: ${repo} redirected to repository ${id}, answered for ${show(moved?.id)}, ${show(moved?.full_name)}`)
+    return moved
+  }
+  assert.ok(sameName(info?.full_name, repo), `getRepo: answered for ${show(info?.full_name)}, not ${repo}`)
   return info
 }
 
@@ -175,6 +195,71 @@ async function listRepoDir(headers, options) {
   return await listTree('listRepoDir', headers, options.repo, tree)
 }
 
+// A tree and every tree under it in one listing, their entries by paths
+// from it, or null where GitHub cut it short, as it does past 100,000
+// entries or 7 MB. Each tree in it, the top one too, has to hash from the
+// entries listed in it, so none is left out, changed or added: an entry is
+// filed under the path before its last `/`, a tree's own with a `/` after
+// it, so `/x` or `a//x` is in no tree.
+async function listTreeDeep(method, headers, repo, tree) {
+  const listing = await call(headers, repoApi(repo, ['git', 'trees', tree], { recursive: 1 }))
+  if (listing?.truncated === true) return null
+  const entries = Array.isArray(listing?.tree) && listing.tree.every((entry) => typeof entry?.path === 'string') ? listing.tree : []
+  const dirs = new Map([['', { sha: tree, listed: [] }], ...entries.filter((entry) => entry.type === 'tree').map((entry) => [`${entry.path}/`, { sha: entry.sha, listed: [] }])])
+  const filed = entries.every(({ path, mode, type, sha }) => {
+    const at = path.lastIndexOf('/') + 1
+    const dir = dirs.get(path.slice(0, at))
+    dir?.listed.push({ path: path.slice(at), mode, type, sha })
+    return dir !== undefined
+  })
+  assert.ok(filed && [...dirs.values()].every(({ sha, listed }) => gitTreeOfListing(listed) === sha), `${method}: GitHub's listing of tree ${tree} in ${repo}, with the trees under it, is not that tree`)
+  return entries
+}
+
+// Each file in `tree`, which is at `base` in the repo, by its path, its
+// name and its blob's id: from the tree's listing with every tree under
+// it, or, where GitHub cuts that short, from its own and then each
+// subtree's in turn, as GitHub advises for a large tree. A node_modules,
+// of packages installed, is not the repo's own.
+async function* filesIn(method, headers, repo, tree, base) {
+  const deep = await listTreeDeep(method, headers, repo, tree)
+  for (const { path, mode, type, sha } of deep ?? await listTree(method, headers, repo, tree)) {
+    const names = path.split('/')
+    if (names.includes('node_modules')) continue
+    if (type === 'blob' && mode !== '120000') yield { path: `${base}${path}`, name: names.at(-1), sha }
+    else if (deep === null && type === 'tree') yield* filesIn(method, headers, repo, sha, `${base}${path}/`)
+  }
+}
+
+const byPath = (a, b) => (a.path < b.path ? -1 : 1)
+
+async function findRepoLockfiles(headers, options) {
+  assertArgs('findRepoLockfiles', options, { repo: assertRepo, sha: assertSha, directory: optional(assertPath) })
+  const { repo, sha, directory } = options
+  const tree = await treeAt('findRepoLockfiles', headers, options)
+  const lockfiles = []
+  const projects = new Map()
+  const files = new Map()
+  const locked = []
+  for await (const { path, name, sha: blob } of filesIn('findRepoLockfiles', headers, repo, tree, directory === undefined ? '' : `${directory}/`)) {
+    files.set(path, blob)
+    const lockfile = lockfileOf(name)
+    const formats = projectFormats(name)
+    if (lockfile === undefined && formats.length === 0) continue
+    assertPath('findRepoLockfiles', `${repo}@${sha}'s ${lockfile === undefined ? 'project file' : 'lockfile'}`, path)
+    if (lockfile !== undefined) lockfiles.push({ path, format: lockfile.format, sha: blob })
+    if (lockfile?.locks !== undefined) locked.push({ path: `${path.slice(0, -name.length)}${lockfile.locks}`, format: lockfile.format })
+    if (formats.length > 0) projects.set(path, { path, formats, sha: blob })
+  }
+  // A file a lockfile beside it locks is a project file of that format too.
+  for (const { path, format } of locked) {
+    if (!files.has(path)) continue
+    const formats = projects.get(path)?.formats ?? []
+    projects.set(path, { path, formats: Object.keys(FORMATS).filter((known) => known === format || formats.includes(known)), sha: files.get(path) })
+  }
+  return { lockfiles: lockfiles.toSorted(byPath), projects: [...projects.values()].toSorted(byPath) }
+}
+
 async function getPullRequest(headers, options) {
   assertArgs('getPullRequest', options, { repo: assertRepo, number: assertNumber })
   const { repo, number } = options
@@ -219,5 +304,5 @@ async function listRepoAdvisories(headers, options) {
   return (await Array.fromAsync(cursorPages('listRepoAdvisories', headers, pageUrl))).flat()
 }
 
-export const readMethods = { getCurrentUser, listUserRepos, getRepo, getRepoHead, getRepoTag, listRepoTags, getRepoFile, getRepoTarball, getRepoTreeTarball, getRepoTreeId, listRepoDir, getPullRequest, getCollaboratorPermission, getAdvisory, listRepoAdvisories }
+export const readMethods = { getCurrentUser, listUserRepos, getRepo, getRepoHead, getRepoTag, listRepoTags, getRepoFile, getRepoTarball, getRepoTreeTarball, getRepoTreeId, listRepoDir, findRepoLockfiles, getPullRequest, getCollaboratorPermission, getAdvisory, listRepoAdvisories }
 export const createClient = (options) => bindMethods(clientHeaders('createClient', options, true), readMethods)

package/src/http.js

@@ -32,11 +32,13 @@ const LIMITS = {
 }
 const decoder = new TextDecoder('utf-8', { fatal: true })
 
+// `headers` are the response's, where there was one to read them from.
 export class HttpError extends Error {
-  constructor(status, message) {
+  constructor(status, message, headers) {
     super(message)
     this.name = 'HttpError'
     this.status = status
+    if (headers !== undefined) this.headers = headers
   }
 }
 
@@ -119,7 +121,7 @@ export async function requestWithHeaders(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)}`)
+    throw new HttpError(res.status, `${options.method ?? 'GET'} ${url} ${res.status}: ${printable(text)}`, res.headers)
   }
   return { body: parse(await readBody(res, LIMITS[options.as].bytes), url, options.as), headers: res.headers }
 }

package/src/lockfiles.js

@@ -0,0 +1,113 @@
+// Each tool that writes a lockfile, by the format of it: the names it
+// writes one under, and those of the project files it locks, each a name
+// as git has it, `cargo.lock` not Cargo's, or a pattern. A lockfile's
+// pattern names in a `locks` group the file beside it that it locks, where
+// no name of that file's own tells it is one.
+export const FORMATS = {
+  // pnpm-lock.<branch>.yaml with git-branch-lockfile; shrinkwrap.yaml before
+  // pnpm 3. package.yaml and package.json5 in place of package.json, and
+  // .pnpmfile's hooks, which change what is locked.
+  pnpm: {
+    lockfiles: ['pnpm-lock.yaml', /^pnpm-lock\..+\.yaml$/u, 'shrinkwrap.yaml'],
+    projects: ['package.json', 'package.yaml', 'package.json5', 'pnpm-workspace.yaml', '.pnpmfile.cjs', '.pnpmfile.mjs'],
+  },
+  // npm-shrinkwrap.json is npm's own format, which npm reads before a
+  // package-lock.json beside it.
+  npm: { lockfiles: ['package-lock.json', 'npm-shrinkwrap.json'], projects: ['package.json'] },
+  // Of Yarn 1 or a later Yarn, which only the text tells apart. .yarnrc.yml
+  // has Yarn 4's catalogs.
+  yarn: { lockfiles: ['yarn.lock'], projects: ['package.json', '.yarnrc.yml'] },
+  // bun.lockb is Bun's binary one, before Bun 1.2.
+  bun: { lockfiles: ['bun.lock', 'bun.lockb'], projects: ['package.json'] },
+  deno: { lockfiles: ['deno.lock'], projects: ['deno.json', 'deno.jsonc', 'package.json'] },
+  // <script>.py.lock, of `uv lock --script`, which locks the script.
+  uv: { lockfiles: ['uv.lock', /^(?<locks>.+\.py)\.lock$/u], projects: ['pyproject.toml'] },
+  poetry: { lockfiles: ['poetry.lock'], projects: ['pyproject.toml'] },
+  // PEP 751's.
+  pylock: { lockfiles: ['pylock.toml', /^pylock\.[^.]+\.toml$/u], projects: ['pyproject.toml'] },
+  pipenv: { lockfiles: ['Pipfile.lock'], projects: ['Pipfile'] },
+  pdm: { lockfiles: ['pdm.lock'], projects: ['pyproject.toml'] },
+  pixi: { lockfiles: ['pixi.lock'], projects: ['pixi.toml', 'pyproject.toml'] },
+  // A unified lockfile of another name has to end in `.conda-lock.yml`; the
+  // explicit and env ones are conda-<platform>.lock and .lock.yml. A
+  // conda-build recipe, meta.yaml, is a source too.
+  'conda-lock': {
+    lockfiles: ['conda-lock.yml', 'conda-lock.yaml', /^.+\.conda-lock\.yml$/u, /^conda-[\da-z]+-[\da-z]+\.lock(?:\.yml)?$/u],
+    projects: ['environment.yml', 'environment.yaml', 'meta.yaml', 'pyproject.toml'],
+  },
+  // A gemspec, whose dependencies a Gemfile's `gemspec` takes.
+  bundler: { lockfiles: ['Gemfile.lock', 'gems.locked'], projects: ['Gemfile', 'gems.rb', /^.+\.gemspec$/u] },
+  composer: { lockfiles: ['composer.lock'], projects: ['composer.json'] },
+  cargo: { lockfiles: ['Cargo.lock'], projects: ['Cargo.toml'] },
+  soldeer: { lockfiles: ['soldeer.lock'], projects: ['soldeer.toml', 'foundry.toml'] },
+  foundry: { lockfiles: ['foundry.lock'], projects: ['foundry.toml'] },
+  // Each name CocoaPods reads a Podfile under, and a podspec, whose
+  // dependencies a Podfile's `podspec` takes.
+  cocoapods: { lockfiles: ['Podfile.lock'], projects: ['Podfile', 'Podfile.rb', 'CocoaPods.podfile', 'CocoaPods.podfile.yaml', /^.+\.podspec(?:\.json)?$/u] },
+  swiftpm: { lockfiles: ['Package.resolved'], projects: ['Package.swift', /^Package@swift-\d+(?:\.\d+){0,2}\.swift$/u] },
+  carthage: { lockfiles: ['Cartfile.resolved'], projects: ['Cartfile', 'Cartfile.private'] },
+  // go.sum has the checksums; go.mod, the versions, is locked as it is. A
+  // workspace's go.work.sum has those its modules' go.sum do not.
+  go: { lockfiles: ['go.sum', 'go.work.sum'], projects: ['go.mod', 'go.work'] },
+  dep: { lockfiles: ['Gopkg.lock'], projects: ['Gopkg.toml'] },
+  // packages.<project>.lock.json, for one of projects that share a
+  // directory; Directory.Packages.props has the versions of Central
+  // Package Management, which the project files then leave out.
+  nuget: { lockfiles: ['packages.lock.json', /^packages\..+\.lock\.json$/u], projects: [/^.+\.(?:cs|fs|vb)proj$/u, 'Directory.Packages.props'] },
+  paket: { lockfiles: ['paket.lock'], projects: ['paket.dependencies'] },
+  // Any *.lockfile: Gradle's own, the legacy one of each configuration, or
+  // one a build names. Version catalogs, libs.versions.toml and the like.
+  gradle: { lockfiles: [/^.+\.lockfile$/u], projects: ['build.gradle', 'build.gradle.kts', 'settings.gradle', 'settings.gradle.kts', /^.+\.versions\.toml$/u] },
+  // pubspec_overrides.yaml overrides pubspec.yaml's dependency_overrides,
+  // workspace and resolution.
+  pub: { lockfiles: ['pubspec.lock'], projects: ['pubspec.yaml', 'pubspec_overrides.yaml'] },
+  mix: { lockfiles: ['mix.lock'], projects: ['mix.exs'] },
+  // rebar.config.script, where there is one, makes the configuration.
+  rebar: { lockfiles: ['rebar.lock'], projects: ['rebar.config', 'rebar.config.script'] },
+  julia: { lockfiles: ['Manifest.toml', 'JuliaManifest.toml', /^(?:Julia)?Manifest-v\d+\.\d+\.toml$/u], projects: ['Project.toml', 'JuliaProject.toml'] },
+  // Each of a configuration's name, stack.yaml or another, and `.lock`.
+  stack: { lockfiles: [/^(?<locks>.+\.ya?ml)\.lock$/u], projects: ['stack.yaml'] },
+  // Each of a project file's name, cabal.project or another, and `.freeze`.
+  cabal: { lockfiles: [/^(?<locks>.+)\.freeze$/u], projects: ['cabal.project', /^.+\.cabal$/u] },
+  shards: { lockfiles: ['shard.lock'], projects: ['shard.yml', 'shard.override.yml'] },
+  opam: { lockfiles: ['opam.locked', /^.+\.opam\.locked$/u], projects: ['opam', /^.+\.opam$/u] },
+  nix: { lockfiles: ['flake.lock'], projects: ['flake.nix'] },
+  conan: { lockfiles: ['conan.lock'], projects: ['conanfile.txt', 'conanfile.py'] },
+  // <name>.MODULE.bazel, which MODULE.bazel's include() takes.
+  bazel: { lockfiles: ['MODULE.bazel.lock'], projects: ['MODULE.bazel', /^[^.].*\.MODULE\.bazel$/u] },
+  helm: { lockfiles: ['Chart.lock'], projects: ['Chart.yaml'] },
+  // Of no project file, but the library it is made from.
+  renv: { lockfiles: ['renv.lock'], projects: [] },
+  // Of the configuration in the directory, each of its .tf files, a child
+  // module's too, of which there is none; OpenTofu's .tofu files, and a
+  // Stack's components.
+  terraform: { lockfiles: ['.terraform.lock.hcl'], projects: [/^.+\.(?:tf|tofu)(?:\.json)?$/u, /^.+\.tfcomponent\.hcl$/u] },
+}
+
+const TOOLS = Object.entries(FORMATS)
+const KNOWN = TOOLS.flatMap(([, { lockfiles, projects }]) => [...lockfiles, ...projects])
+
+// A name of none of them, as most in a repository are, is passed over at
+// once, by a set of the names and one pattern of all the patterns.
+const NAMES = new Set(KNOWN.filter((known) => typeof known === 'string'))
+const PATTERN = new RegExp(KNOWN.filter((known) => typeof known !== 'string').map(({ source }) => `(?:${source})`).join('|'), 'u')
+const isKnown = (name) => NAMES.has(name) || PATTERN.test(name)
+
+// Whether `name` is one of `names`, each a name or a pattern.
+const isOf = (names, name) => names.some((known) => (typeof known === 'string' ? known === name : known.test(name)))
+
+// The lockfile a file of this name is, `{ format, locks }`, `locks` the name
+// of the file beside it that it locks where its pattern names one; or
+// undefined.
+export function lockfileOf(name) {
+  for (const [format, { lockfiles }] of isKnown(name) ? TOOLS : []) {
+    for (const known of lockfiles) {
+      const match = typeof known === 'string' ? known === name && {} : known.exec(name)
+      if (match) return { format, locks: match.groups?.locks }
+    }
+  }
+}
+
+// The formats of the lockfiles that lock a project of a file of this name,
+// in FORMATS' order, none where it is no project file.
+export const projectFormats = (name) => (isKnown(name) ? TOOLS.filter(([, { projects }]) => isOf(projects, name)).map(([format]) => format) : [])