@preventive/upstream 1.0.0-alpha.8 → 1.0.0

package/advisories.d.ts

@@ -2,8 +2,10 @@
 // other.
 
 import type { Client, RepoName } from './github.js'
+import type { CacheStore } from './npm.js'
 
 export { HttpError } from './npm.js'
+export type { CacheStore } from './npm.js'
 
 // As purl and stasis name them.
 export type Ecosystem = 'npm' | 'cargo' | 'composer' | 'soldeer' | 'github'
@@ -36,9 +38,16 @@ export interface AdvisoryOptions {
   // Also asks each npm, cargo and composer package's GitHub repository
   // for its published advisories, which it has before GitHub reviews them
   // into the databases above: the package's `github` where given, else
-  // the one npm's metadata, crates.io or Packagist names, looked up
-  // through the cache. Needs `github`.
+  // the one looked up. An npm package's is the one the document of its
+  // newest version asked names, kept for good as getMeta keeps it (none
+  // where the registry does not have that version); a crate's and a
+  // composer package's, the one crates.io or Packagist names, kept a
+  // month. Needs `github`.
   repoAdvisories?: boolean
+  // Where what this call caches is kept, as CacheOptions (npm.js) has it:
+  // a repository's listing, and each package's repository looked up (an
+  // npm package's as its version's document). See `advisories`.
+  cache?: CacheStore | false
   // Also returns each advisory's full text, as `details`. OSV's records
   // and a repository's listing already carry it; npm's registry does not,
   // and its rows take OSV's record of their GHSA, one more request each
@@ -53,7 +62,7 @@ export interface Advisory {
   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
+  // 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.
@@ -62,17 +71,17 @@ export interface Advisory {
   // under that GHSA. The only source for `soldeer` and `github`, where
   // every range counts, whichever package it names.
   source: 'registry' | 'osv' | 'repository'
-  // A GHSA, RUSTSEC-…, MAL-…, DRUPAL-CORE-… or another OSV id, or
+  // A GHSA, RUSTSEC-..., MAL-..., DRUPAL-CORE-... or another OSV id, or
   // npm:<id> for a registry row without a GHSA.
   id: string
   // The id itself, or an OSV record's one GHSA alias.
   ghsa?: string
   // GitHub's page for the GHSA, with it: a `repository` row's on its
-  // repository (https://github.com/owner/name/security/advisories/GHSA-…),
+  // repository (https://github.com/owner/name/security/advisories/GHSA-...),
   // which has it before GitHub reviews it into its advisory database; any
-  // other's in that database (https://github.com/advisories/GHSA-…). An
+  // other's in that database (https://github.com/advisories/GHSA-...). An
   // `osv` row without one has osv.dev's page for its record
-  // (https://osv.dev/vulnerability/RUSTSEC-…). Built, never fetched: only
+  // (https://osv.dev/vulnerability/RUSTSEC-...). Built, never fetched: only
   // a registry row without a GHSA (npm:<id>) has none.
   url?: string
   aliases: string[]
@@ -108,6 +117,11 @@ export interface Advisory {
 // 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.
+// 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
+// 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.
 export function advisories(packages: Iterable<Package>, options?: AdvisoryOptions): Promise<Advisory[]>

package/git.d.ts

@@ -6,8 +6,8 @@ export interface GitCheckout {
   // `owner/name`, when the origin remote is a GitHub one. Never the
   // remote's URL, which can name a private host or carry a token.
   github?: string
-  // Where the directory sits in its checkout, `/`-separated; absent at
-  // the root.
+  // Where the directory sits in its checkout, `/`-separated; `''` at the
+  // root.
   directory?: string
   // `https://github.com/<github>`, whenever there is a `github`.
   url?: string

package/npm.d.ts

@@ -7,8 +7,9 @@
 // a timeout, as github.d.ts describes, and lookups for many names go to
 // the registry eight at a time.
 //
-// Where NPM_TOKEN is set, it is sent with the requests for a scoped
-// package, so a private one can be read.
+// Where PREVENTIVE_MEASURES_NPM_TOKEN, STASIS_NPM_TOKEN or NPM_TOKEN is
+// set, the first of them not empty, in that order, is sent with the
+// requests for a scoped package, so a private one can be read.
 
 // Where a program called `name` keeps its cache for this user, as each
 // platform has it, read from the environment when called. macOS:
@@ -32,14 +33,45 @@ export const defaultCacheDir: string | undefined
 // cache: every read of it misses and every write is skipped. getTarball
 // reads ours all the same, set or not.
 //
-// The directory is trusted: a package's repo is answered from it as it
-// was written, with no request. Point it only at storage that nothing
-// less trusted than the caller can write, never a cache shared with or
-// restored from lower-trust jobs. Tarballs, crates (cargo.js), zips
+// The directory is trusted: a package's repo, as recorded or as a version
+// document kept here names it, and for 90 minutes a repository's published
+// advisories (advisories.js), are answered from it as they were written,
+// with no request. Point it only at storage that
+// nothing less trusted than the caller can write, never a cache shared
+// with or restored from lower-trust jobs. Tarballs, crates (cargo.js), zips
 // (soldeer.js) and tree tarballs (github.js) don't rely on this, since
-// they are checked against their integrity on every call.
+// they are checked against their integrity on every call; and the version
+// documents kept here (getMeta) never supply an integrity, only confirm
+// one a caller gives (verifyDist, and getMeta with a `dist`). A call's `cache` option, where it has
+// one, keeps what it caches elsewhere, or writes none of it here.
 export function setCacheDir(dir?: string | false): void
 
+// A store of the caller's, a database's say, for what would otherwise be
+// kept in setCacheDir's cache: `read` answers the value last written
+// under that `type` and `key`, or null or undefined for none. A `type` is
+// what is kept and a `key` which one: `npm/versions` and `npm/tarballs`
+// with `<name>@<version>` for a version's document and tarball; and for
+// advisories.js, `github/advisories` with the repository's `owner/name` in
+// lowercase for its listing, and `cargo/repos`, `composer/repos` and
+// `soldeer/repos` with a package's name for the repository it names.
+// Values are plain JSON data, which `read` may answer as written or as a
+// copy, but a tarball's are its bytes, a Uint8Array. Whatever it answers
+// is checked as a cached file is: one malformed, stale or kept differently
+// is a miss, and a tarball's bytes that do not match throw. A rejection
+// from either is the call's. It is trusted as setCacheDir's directory is.
+export interface CacheStore {
+  read(type: string, key: string): Promise<unknown>
+  write(type: string, key: string, value: unknown): Promise<void>
+}
+
+// Where a call keeps what it caches: in setCacheDir's cache where `cache`
+// is left out; in a store of the caller's in place of it; or with `false`,
+// nowhere, though setCacheDir's cache is read all the same. Other tools'
+// caches and ours are read for tarballs whatever it is (getTarball).
+export interface CacheOptions {
+  cache?: CacheStore | false
+}
+
 // A failed request: `status` is the HTTP status the registry answered
 // with (404 for a package or version it does not have).
 export class HttpError extends Error {
@@ -47,11 +79,11 @@ export class HttpError extends Error {
   status: number
 }
 
-// A package's GitHub repo as its registry metadata names it — getRepo
+// A package's GitHub repo as its registry metadata names it -- getRepo
 // (package.js) over its `latest` document: `github` is `owner/name`, and
-// `directory` is where in the repo the package sits, absent for a
-// package at the repo root. Throws when the package cannot be fetched or
-// names no GitHub repo.
+// `directory` is where in the repo the package sits, `''` at the repo
+// root, absent where it declares none. Throws when the package cannot be
+// fetched or names no GitHub repo.
 export interface GitHubLink {
   github: string
   directory?: string
@@ -71,7 +103,10 @@ export function resolvePackageRepos(packageNames: Iterable<string>, options?: {
 // The disk cache resolvePackageRepos reads and writes, a month per entry.
 // A read answers null for anything but a usable entry, one written by a
 // release that resolved repos by other rules included; a write answers
-// false where it could not write, and never throws.
+// false where it could not write, and never throws. A write takes the
+// `github` a lookup gives, `owner/name` with no trailing `.git`, so what
+// it writes reads back; a `directory` left out is unknown, and `''` the
+// repo root.
 export function readPackageRepoCache(name: string): Promise<PackageRepo | null>
 export function writePackageRepoCache(name: string, github: string, directory?: string): Promise<boolean>
 
@@ -84,25 +119,83 @@ export interface Dist {
   integrity: string
 }
 
+// `gitHead` is the commit the document names, as npm reads it off the git
+// checkout it publishes from, where it is a full commit id: 40 lowercase
+// hex digits, or 64. `repository`, `homepage` and `bugs` are the
+// document's, as the package.json published had them, or npm filled them
+// in from one another: each a string as it is, or for `repository` and
+// `bugs` an object, of which only the strings named below are read. Each is
+// absent where the document has none, or has another shape, or an object
+// with none of those strings. All of it is the publisher's word, held to no
+// repository.
 export interface PackageMeta {
   name: string
   version: string
   dist: Dist
+  gitHead?: string
+  repository?: string | PackageRepository
+  homepage?: string
+  bugs?: string | PackageBugs
+}
+
+export interface PackageRepository {
+  type: string | undefined
+  url: string | undefined
+  directory: string | undefined
+}
+
+export interface PackageBugs {
+  url: string | undefined
+  email: string | undefined
+}
+
+// getMeta's options: `cache`, and the `dist` a caller already has of that
+// version, as a lockfile gives it, held to the rules above.
+export interface MetaOptions extends CacheOptions {
+  dist?: Dist
 }
 
 // The registry's version document, refused unless it is for that name and
 // version and its dist is held to the rules above.
-export function getMeta(name: string, version: string): Promise<PackageMeta>
+//
+// With `dist`, npm's own cache comes first, where getTarball looks for
+// npm's tarballs: where it keeps the full packument of that name, as npm 10
+// and later fetch it, and that version's entry there has the given dist's
+// tarball and integrity, that entry answers, with no request, and neither
+// `cache` nor setCacheDir's cache is read or written. An abbreviated
+// packument, as earlier npm fetches, is passed over, as is one whose
+// content does not match the sha512 npm filed it by. What it answers
+// beside the dist is taken from npm's cache as it is from setCacheDir's.
+// Else the document `cache` keeps answers, with no request, where its
+// tarball and integrity are the given dist's; else the registry's is asked
+// for, and throws where they are not.
+//
+// Without `dist`, the registry is asked on every call: a cache never
+// supplies a dist. Kept whole, as `cache` says, and for good once it
+// passes, as the registry never takes a version twice: in setCacheDir's
+// cache, compressed, where `cache` is left out. One refused is not kept.
+export function getMeta(name: string, version: string, options?: MetaOptions): Promise<PackageMeta>
+
+// When the registry says each version of a package it lists was published,
+// by version, as Date#toISOString writes it: from the whole package's
+// document, the only one with `time`, megabytes for some. A version whose
+// time is missing, not an ISO 8601 UTC time, or not one there is, as
+// 2018-02-29, is left out. Refused unless the document is for that name.
+export function getPublishTimes(name: string): Promise<Map<string, string>>
 
-// Fetches the registry's dist for that version and throws unless its
-// integrity is the one given, as for a dist read off a lockfile.
-export function verifyDist(name: string, version: string, dist: Dist): Promise<void>
+// Throws unless the integrity of that version is the one given, as for a
+// dist read off a lockfile: by the version document `cache` keeps, with no
+// request, else by the registry's, kept then as getMeta keeps it. One kept
+// with another integrity, refused, or for another name or version, is
+// passed over for the registry's, which throws where it has another.
+export function verifyDist(name: string, version: string, dist: Dist, options?: CacheOptions): Promise<void>
 
 // A published version's gzipped tarball, whole, in memory. Without `dist`,
-// the version document is fetched on every call, cached tarball or not;
-// with one, it is trusted as given and nothing but the tarball is asked
-// for. Either way the bytes are checked against `dist.integrity`, whether
-// they were downloaded (before they are cached) or read from a cache.
+// the version document is fetched on every call, cached tarball or not,
+// and kept as getMeta keeps it; with one, it is trusted as given and
+// nothing but the tarball is asked for. Either way the bytes are checked
+// against `dist.integrity`, whether they were downloaded (before they are
+// cached) or read from a cache.
 //
 // Other caches are read first, and never written: npm's (cacache under
 // npm_config_cache, else npm's default, `~/.npm` outside Windows; and npm
@@ -110,5 +203,7 @@ export function verifyDist(name: string, version: string, dist: Dist): Promise<v
 // `~/.audit/cache/tgz/<org>:<name>-<version>.tgz`, then defaultCacheDir
 // and cacheDirFor('stasis'), as setCacheDir files a tarball in either,
 // whether set or not. A file there that does not match is passed over.
-// Then setCacheDir's cache, where one that does not match throws.
-export function getTarball(name: string, version: string, dist?: Dist): Promise<Uint8Array>
+// Then setCacheDir's cache, or a `cache` store in its place, where bytes
+// that do not match throw. A tarball downloaded is kept there, unless
+// `cache` is false.
+export function getTarball(name: string, version: string, dist?: Dist, options?: CacheOptions): Promise<Uint8Array>

package/npm.js

@@ -1,4 +1,4 @@
 export { cacheDirFor, defaultCacheDir, setCacheDir } from './src/cache.js'
 export { HttpError } from './src/http.js'
 export { getGitHub, readPackageRepoCache, resolvePackageRepos, writePackageRepoCache } from './src/npm/repos.js'
-export { getMeta, getTarball, verifyDist } from './src/npm/tarball.js'
+export { getMeta, getPublishTimes, getTarball, verifyDist } from './src/npm/tarball.js'

package/package.d.ts

@@ -4,8 +4,11 @@ export interface PackageRepoLink {
   // `owner/name`, by GitHub's own rules.
   github?: string
   // Where in that repo the package sits, `/`-separated, as the tree path
-  // itself (a homepage URL's decoded); absent at its root, and whenever
-  // `github` is.
+  // itself (a homepage URL's decoded; a `repository.directory`'s `\` read
+  // as `/`, its empty and `.` parts dropped); `''` at its root, where
+  // `repository.directory` declares it (`./`, `/`, `/.`, `.`, `''`). Absent
+  // where unknown: neither field names a directory in it (one with a `..`
+  // part names none), and whenever `github` is absent.
   directory?: string
   // `https://github.com/<github>`, whenever there is a `github`.
   url?: string

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@preventive/upstream",
-  "version": "1.0.0-alpha.8",
+  "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",
   "type": "module",
   "exports": {
@@ -39,6 +39,10 @@
     "./soldeer.js": {
       "types": "./soldeer.d.ts",
       "default": "./soldeer.js"
+    },
+    "./weak-edges.js": {
+      "types": "./weak-edges.d.ts",
+      "default": "./weak-edges.js"
     }
   },
   "files": [
@@ -62,6 +66,8 @@
     "semver.js",
     "soldeer.d.ts",
     "soldeer.js",
+    "weak-edges.d.ts",
+    "weak-edges.js",
     "src/advisories/common.js",
     "src/advisories/github.js",
     "src/advisories/index.js",
@@ -79,16 +85,19 @@
     "src/github/read.js",
     "src/github/write.js",
     "src/http.js",
+    "src/npm/cacache.js",
     "src/npm/registry.js",
     "src/npm/repos.js",
     "src/npm/tarball.js",
+    "src/npm/versions.js",
     "src/package.js",
     "src/pool.js",
     "src/remote.js",
     "src/semver-peer.cjs",
     "src/semver.js",
     "src/tree.js",
-    "src/soldeer.js"
+    "src/soldeer.js",
+    "src/weak-edges.js"
   ],
   "engines": {
     "node": ">=24.14.0"

package/src/advisories/github.js

@@ -1,13 +1,21 @@
 import assert from 'node:assert/strict'
 
 import { assertRepo, assertSoldeerName, assertSoldeerVersion, assertion, isGhsa, isRefName, isStrings } from '../args.js'
+import { readRecord, writeRecord } from '../cache.js'
 import { isGone } from '../github/client.js'
 import { recover } from '../http.js'
 import { pool } from '../pool.js'
+import { isExactVersion } from '../semver.js'
 import { advisoryUrl, covered, detailsOf, isText, mayBeInRange, metrics } from './common.js'
 import { soldeerRepos } from './repos.js'
 
 const REPOS_AT_ONCE = 4
+const DIR = 'github/advisories'
+// A maintainer publishes one whenever they are ready, and seeing it before
+// GitHub reviews it is what a repository is asked for: 90 minutes, not a month.
+const LISTING_TTL_MS = 90 * 60 * 1000
+// Stamped on each entry, and raised when a listing is kept differently.
+const VERSION = 2
 
 const isRepoAdvisory = (advisory) => advisory && typeof advisory === 'object' && isGhsa(advisory.ghsa_id)
   && advisory.state === 'published' && isText(advisory.summary)
@@ -15,7 +23,63 @@ const isRepoAdvisory = (advisory) => advisory && typeof advisory === 'object' &&
 
 export const assertClient = assertion('a GitHub client from createClient', (value) => typeof value?.listRepoAdvisories === 'function')
 
-const listAdvisories = (github, repo) => github.listRepoAdvisories({ repo }).catch(recover(isGone, []))
+// 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`),
+// as GitHub's page shows them side by side: such a range ends below its one
+// patched version. A range bounded above, or patched in more than one
+// version, is as given.
+function boundedRange(range, patched) {
+  const fixed = typeof patched === 'string' ? patched.trim() : null
+  if (!isExactVersion(fixed) || range.includes('<')) return range
+  return range.trim() === '' ? `< ${fixed}` : `${range.trim()}, < ${fixed}`
+}
+
+// What rows are made from, and all that is kept of a listing: each advisory
+// not withdrawn, with its CVSS vector GitHub prefers, and each vulnerable
+// range with the package it names, ended below its patched version where it
+// has no end of its own (boundedRange). A listing that is malformed is
+// refused whole, and never kept; one whose only fault is a description
+// (isDigest) is answered, but not kept either.
+function digest(repo, list) {
+  return list.flatMap((advisory) => {
+    assert.ok(isRepoAdvisory(advisory), `advisories: malformed advisory from ${repo}`)
+    if (advisory.withdrawn_at) return []
+    const cvss = [advisory.cvss_severities?.cvss_v3, advisory.cvss_severities?.cvss_v4, advisory.cvss].find((entry) => typeof entry?.vector_string === 'string')
+    const ranges = (advisory.vulnerabilities ?? []).map((vulnerability) => {
+      const range = vulnerability?.vulnerable_version_range ?? ''
+      assert.ok(typeof range === 'string', `advisories: malformed range in ${advisory.ghsa_id}`)
+      const { ecosystem, name } = vulnerability?.package ?? {}
+      return { range: boundedRange(range, vulnerability?.patched_versions), ...(typeof ecosystem === 'string' && { ecosystem }), ...(typeof name === 'string' && { name }) }
+    })
+    return [{
+      ghsa: advisory.ghsa_id,
+      title: advisory.summary,
+      ...(advisory.description != null && advisory.description !== '' && { description: advisory.description }),
+      ...metrics({ severity: advisory.severity, score: cvss?.score, vector: cvss?.vector_string, cwe: advisory.cwe_ids }),
+      ranges,
+    }]
+  })
+}
+
+// A description is checked only for `details` (detailsOf), so a malformed
+// one leaves the listing usable, but not kept.
+const isDigest = (advisory) => advisory && typeof advisory === 'object' && isGhsa(advisory.ghsa) && isText(advisory.title)
+  && (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.
+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
+}
 
 // GitHub's `>= 1.0.0, < 1.2.6` is npm's with the commas dropped.
 // Maintainers write these unreviewed: one without a range, or with one
@@ -23,17 +87,16 @@ const listAdvisories = (github, repo) => github.listRepoAdvisories({ repo }).cat
 // may publish it long before the advisory database has one, and its
 // `description` is the text `details` asks for: the listing has it all.
 function fromRepository(repo, name, advisory, range, asked, { covers, details }) {
-  const cvss = [advisory.cvss_severities?.cvss_v3, advisory.cvss_severities?.cvss_v4, advisory.cvss].find((entry) => typeof entry?.vector_string === 'string')
   return {
     name,
     source: 'repository',
-    id: advisory.ghsa_id,
-    ghsa: advisory.ghsa_id,
-    url: advisoryUrl(advisory.ghsa_id, repo),
+    id: advisory.ghsa,
+    ghsa: advisory.ghsa,
+    url: advisoryUrl(advisory.ghsa, repo),
     aliases: [],
-    title: advisory.summary,
-    ...(details && detailsOf(advisory.description, advisory.ghsa_id)),
-    ...metrics({ severity: advisory.severity, score: cvss?.score, vector: cvss?.vector_string, cwe: advisory.cwe_ids }),
+    title: advisory.title,
+    ...(details && detailsOf(advisory.description, advisory.ghsa)),
+    ...metrics({ severity: advisory.severity, score: advisory.cvss, vector: advisory.cvssVector, cwe: advisory.cwe }),
     range,
     versions: covered(asked, range.replaceAll(',', ' '), covers),
   }
@@ -41,21 +104,18 @@ function fromRepository(repo, name, advisory, range, asked, { covers, details })
 
 // Each asked name's repository, `repoOf` it, is asked once, and its
 // advisories' vulnerable ranges become rows for the names that `takes` a
-// vulnerability, one per name, advisory and range, holding the asked
+// range's package, one per name, advisory and range, holding the asked
 // versions it `covers`, and with `details`, its text.
-async function repositoryAdvisories(github, asked, { repoOf, takes = () => true, 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])) }))
+  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 rows = new Map()
   for (const { repo, names, list } of listed) {
     for (const advisory of list) {
-      assert.ok(isRepoAdvisory(advisory), `advisories: malformed advisory from ${repo}`)
-      for (const vulnerability of advisory.withdrawn_at ? [] : advisory.vulnerabilities ?? []) {
-        const range = vulnerability?.vulnerable_version_range ?? ''
-        assert.ok(typeof range === 'string', `advisories: malformed range in ${advisory.ghsa_id}`)
-        for (const name of names.filter((candidate) => takes(candidate, vulnerability?.package))) {
-          rows.set(`${name} ${advisory.ghsa_id} ${range}`, fromRepository(repo, name, advisory, range, asked.get(name), { covers, details }))
+      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 }))
         }
       }
     }
@@ -63,9 +123,10 @@ async function repositoryAdvisories(github, asked, { repoOf, takes = () => true,
   return [...rows.values()]
 }
 
-// Each asked name's repository: as given, `known`, or else looked up.
-async function reposOf(asked, known, lookUp) {
-  const found = await lookUp([...asked.keys()].filter((name) => !known.has(name)))
+// Each asked name's repository: as given, `known`, or else looked up,
+// through `cache`.
+async function reposOf(asked, known, lookUp, cache) {
+  const found = await lookUp([...asked.keys()].filter((name) => !known.has(name)), { asked, cache })
   return (name) => known.get(name) ?? found.get(name)
 }
 
@@ -74,12 +135,12 @@ async function reposOf(asked, known, lookUp) {
 // each package's repository, `known` or else looked up, adds what it
 // publishes for GitHub's `ecosystem` entries naming the package, for the
 // versions `rows` do not already report under that GHSA.
-export async function withRepositories(rows, asked, { github, repoAdvisories, known, details }, { ecosystem, lookUp, covers }) {
+export async function withRepositories(rows, asked, { github, repoAdvisories, known, details, cache }, { ecosystem, lookUp, covers }) {
   if (!repoAdvisories) return rows
   const reported = new Set(rows.flatMap((row) => [row.id, row.ghsa, ...row.aliases].filter(isGhsa).flatMap((id) => row.versions.map((version) => `${row.name} ${id} ${version}`))))
-  const repoOf = await reposOf(asked, known, lookUp)
-  const takes = (name, pkg) => pkg?.ecosystem === ecosystem && pkg.name === name
-  const added = await repositoryAdvisories(github, asked, { repoOf, takes, covers, details })
+  const repoOf = await reposOf(asked, known, lookUp, cache)
+  const takes = (name, pkg) => pkg.ecosystem === ecosystem && pkg.name === name
+  const added = await repositoryAdvisories(github, asked, { repoOf, takes, covers, details, cache })
   return [...rows, ...added.map((row) => ({ ...row, versions: row.versions.filter((version) => !reported.has(`${row.name} ${row.id} ${version}`)) }))]
 }
 
@@ -93,7 +154,7 @@ export const GITHUB = {
   repositoryOnly: true,
   assertName: assertRepo,
   assertVersion: assertion('a version or a branch name', isRefName),
-  advisories: (asked, { github, details }) => repositoryAdvisories(github, asked, { repoOf: (repo) => repo, covers: coversPlaceholder, details }),
+  advisories: (asked, { github, details, cache }) => repositoryAdvisories(github, asked, { repoOf: (repo) => repo, covers: coversPlaceholder, details, cache }),
 }
 
 // Soldeer packages, which no advisory database has: the repository each
@@ -104,5 +165,5 @@ export const SOLDEER = {
   repositoryOnly: true,
   assertName: assertSoldeerName,
   assertVersion: assertSoldeerVersion,
-  advisories: async (asked, { github, known, details }) => await repositoryAdvisories(github, asked, { repoOf: await reposOf(asked, known, soldeerRepos), details }),
+  advisories: async (asked, { github, known, details, cache }) => await repositoryAdvisories(github, asked, { repoOf: await reposOf(asked, known, soldeerRepos, cache), details, cache }),
 }

package/src/advisories/index.js

@@ -1,6 +1,7 @@
 import assert from 'node:assert/strict'
 
 import { assertArgs, assertBoolean, assertRepo, assertion, isIterable, optional, sameName } from '../args.js'
+import { assertCache } from '../cache.js'
 import { order } from './common.js'
 import { GITHUB, SOLDEER, assertClient } from './github.js'
 import { NPM } from './npm.js'
@@ -11,7 +12,7 @@ const byNumbers = new Intl.Collator('en', { numeric: true }).compare
 const assertEcosystem = assertion(`one of ${Object.keys(ECOSYSTEMS).join(', ')}`, (value) => typeof value === 'string' && Object.hasOwn(ECOSYSTEMS, value))
 const assertVersions = assertion('a non-empty array', (value) => Array.isArray(value) && value.length > 0)
 
-// Ecosystem → name → { versions, github? }, a name given twice merged.
+// Ecosystem -> name -> { versions, github? }, a name given twice merged.
 // Every package is checked before any is used.
 function collect(packages) {
   assert.ok(isIterable(packages), 'advisories: packages must be an iterable of { ecosystem, name, github?, versions }')
@@ -34,7 +35,7 @@ function collect(packages) {
 }
 
 export async function advisories(packages, options = {}) {
-  assertArgs('advisories', options, { github: optional(assertClient), repoAdvisories: optional(assertBoolean), details: optional(assertBoolean) })
+  assertArgs('advisories', options, { github: optional(assertClient), repoAdvisories: optional(assertBoolean), details: 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`)
@@ -43,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 })
+    const rows = await find(asked, { github: options.github, repoAdvisories: options.repoAdvisories === true, details: options.details === 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/osv.js

@@ -13,12 +13,12 @@ const QUERIES_PER_REQUEST = 1000
 export const RECORDS_AT_ONCE = 8
 const isOsvId = matches(/^(?=.{1,128}$)[A-Z][\dA-Z]*(?:-[\dA-Za-z]+)+$/u)
 // osv.dev's page for one of its records. An id that is only another's
-// alias (PKSA-…) has none, and redirects to a search.
+// alias (PKSA-...) has none, and redirects to a search.
 const osvPage = (id) => `https://osv.dev/vulnerability/${id}`
 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.
+// 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)
@@ -88,7 +88,7 @@ function toAdvisory(ecosystem, name, versions, record, details) {
 async function osvAdvisories(ecosystem, asked, options) {
   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
+  const hits = new Map() // id -> name -> versions, in `list` order
   for (const chunk of chunks(list, QUERIES_PER_REQUEST)) {
     const body = { queries: chunk.map(({ name, version }) => ({ package: { name, ecosystem: osv }, version })) }
     const answer = await request(QUERY_URL, { method: 'POST', body, as: 'json' })