@preventive/upstream 1.0.0-alpha.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nikita Skovoroda
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/advisories.d.ts

@@ -0,0 +1,82 @@
+// Hand-written against advisories.js; a change to either belongs with the
+// other.
+
+import type { Client, RepoName } from './github.js'
+
+export { HttpError } from './npm.js'
+
+// As purl and stasis name them.
+export type Ecosystem = 'npm' | 'cargo' | 'composer' | 'github'
+
+export interface Package {
+  ecosystem: Ecosystem
+  // An npm package name, a crate name, a Composer `vendor/name`, or for
+  // `github`, the repository `owner/name` itself.
+  name: string
+  // Its GitHub repository, where the caller knows it (package.json,
+  // Cargo.toml, installed.json), for `repoAdvisories` to ask without
+  // looking it up; not for `github` packages, which are their own.
+  github?: RepoName
+  // npm and `github`: semver; `github` also takes a branch name or 0.0.0,
+  // which every range covers. cargo: semver, build metadata allowed.
+  // composer: a release (`v1.2.3`, `1.2.3.4`, `2.0.0-RC1`), dev versions
+  // refused; one semver cannot read is covered by every range.
+  versions: string[]
+}
+
+export interface AdvisoryOptions {
+  // The client every GitHub request goes through. Required for `github`
+  // packages, whose repository's published advisories are their only
+  // source, and for `repoAdvisories`; by itself it asks nothing else.
+  github?: Client
+  // 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`.
+  repoAdvisories?: boolean
+}
+
+// One advisory on one package, with the versions asked about that it
+// covers (never empty).
+export interface Advisory {
+  ecosystem: Ecosystem
+  name: string
+  // `registry`: npm's, as `npm audit` has it, one row per vulnerable
+  // range. `osv`: RustSec for cargo, OSV's Packagist records for composer.
+  // `repository`: published on the package's repository, one row per
+  // range, holding only the versions the others' answer does not report
+  // under that GHSA.
+  source: 'registry' | 'osv' | 'repository'
+  // A GHSA, RUSTSEC-…, DRUPAL-CORE-…, 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
+  aliases: string[]
+  title?: string
+  // `critical`, `high`, `moderate`, `low`; GitHub's `medium` reads
+  // `moderate`. RustSec has none.
+  severity?: string
+  // Absent where there is no score (npm spells that 0).
+  cvss?: number
+  cvssVector?: string
+  cwe: string[]
+  // As written: npm's syntax from the registry, GitHub's
+  // (`>= 1.0.0, < 1.2.6`) from a repository; OSV rows have none. A
+  // repository range semver cannot read, or none, covers every version.
+  range?: string
+  // RustSec's kind for an advisory that is not a vulnerability as such:
+  // `unmaintained`, `unsound`, `notice`.
+  informational?: string
+  versions: string[]
+}
+
+// Every package, and every one of its versions, is checked against its
+// ecosystem's rules before the first request; a name given twice is
+// merged, and must not name two repositories. npm is asked 250 names a
+// request, OSV 1000 versions; a repository gone, renamed or blocked adds
+// nothing. Any other failure, a malformed answer, or one about something
+// not asked, throws: nothing is left out quietly. Sorted by ecosystem and
+// name. Versions are matched by npm's semver, from the npm beside node.
+export function advisories(packages: Iterable<Package>, options?: AdvisoryOptions): Promise<Advisory[]>

package/advisories.js

@@ -0,0 +1,2 @@
+export { HttpError } from './src/http.js'
+export { advisories } from './src/advisories/index.js'

package/git.d.ts

@@ -0,0 +1,21 @@
+// 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 {
+  // `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.
+  directory?: string
+  // `https://github.com/<github>`, whenever there is a `github`.
+  url?: string
+  // HEAD's commit sha.
+  commit?: string
+}
+
+// The checkout at or above `dir`, found by its closest `.git` (a
+// directory, or a `gitdir:` file) and read without running git. Empty
+// where there is no checkout.
+export function findGitCheckout(dir: string): Promise<GitCheckout>

package/git.js

@@ -0,0 +1 @@
+export { findGitCheckout } from './src/git.js'

package/github/write.d.ts

@@ -0,0 +1,42 @@
+// Hand-written against github/write.js; a change to either belongs with
+// the other. Arguments are checked as github.d.ts describes.
+
+import type { Client, RepoName } from '../github.js'
+
+export { HttpError } from '../github.js'
+
+export interface WriteClientOptions {
+  // Never anonymous.
+  token: string
+  userAgent?: string
+}
+
+export type CommitMessage = string | { headline: string; body?: string }
+
+export interface WriteClient extends Client {
+  // Into the authenticated user's account, or the given organization.
+  // Answers GitHub's repo object; `full_name` names the fork.
+  forkRepo(options: { repo: RepoName; name?: string; organization?: string; defaultBranchOnly?: boolean }): Promise<any>
+  // At the full commit `oid`, or at the head of the default branch
+  // without one.
+  createBranch(options: { repo: RepoName; branch: string; oid?: string }): Promise<any>
+  // A signed commit on an existing branch, through GraphQL
+  // createCommitOnBranch. `expectedHeadOid` defaults to the branch head.
+  createCommit(options: {
+    repo: RepoName
+    branch: string
+    message: CommitMessage
+    additions?: { path: string; contents: string | Uint8Array }[]
+    deletions?: (string | { path: string })[]
+    expectedHeadOid?: string
+  }): Promise<{ oid: string; url: string }>
+  // `head` is `owner:branch` for a pull request from a fork.
+  createPR(options: { repo: RepoName; title: string; head: string; base: string; body?: string; draft?: boolean }): Promise<any>
+}
+
+export function createWriteClient(options: WriteClientOptions): WriteClient
+
+// A GraphQL response's `data`, or a throw carrying the status and body on
+// a transport error (an HttpError, as a REST failure is), malformed JSON
+// or an `errors` array.
+export function parseGraphQLResponse(status: number, text: string): any

package/github/write.js

@@ -0,0 +1,2 @@
+export { createWriteClient, parseGraphQLResponse } from '../src/github/write.js'
+export { HttpError } from '../src/http.js'

package/github.d.ts

@@ -0,0 +1,68 @@
+// 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,
+// full commit shas, paths with no empty, `.` or `..` 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 tarball's, 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.
+
+// `owner/name`.
+export type RepoName = string
+
+export interface ClientOptions {
+  // `null` for an anonymous client, which reads public repositories
+  // without anyone's credentials. Required either way.
+  token: string | null
+  userAgent?: string
+}
+
+export type PullRequestStatus = 'open' | 'draft' | 'closed' | 'merged'
+
+// A failed request: `status` is the HTTP status GitHub answered with.
+export class HttpError extends Error {
+  name: 'HttpError'
+  status: number
+}
+
+// Reads only.
+export interface Client {
+  // 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
+  // `type`). Without `repo`, or with a repository gone, renamed or blocked
+  // (301, 404, 410, 451), GitHub's global database, which has it only once
+  // reviewed; any other failure throws. Refused unless it is the one asked
+  // for, and published.
+  getAdvisory(options: { ghsa: string; repo?: RepoName }): Promise<{ ghsa_id: string } & Record<string, any>>
+  // GitHub's `{ permission, role_name, user }` for `username` on `repo`,
+  // teams, organization and enterprise grants included.
+  getCollaboratorPermission(options: { repo: RepoName; username: string }): Promise<{ permission: string; role_name?: string; user: { login: string; id: number } } & Record<string, any>>
+  getCurrentUser(): Promise<any>
+  // 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>
+  // 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.
+  getRepoFile(options: { repo: RepoName; path: string; ref?: string }): Promise<string>
+  // The head of `branch`, or of the default branch without one.
+  getRepoHead(options: { repo: RepoName; branch?: string }): Promise<{ branch: string; oid: string }>
+  // The repo's gzipped tarball at the full commit `sha`, whole, in memory.
+  getRepoTarball(options: { repo: RepoName; sha: string }): Promise<Uint8Array>
+  // The repository's published security advisories, as GitHub's
+  // repository advisory objects. One page of 100: GitHub pages this list
+  // by cursor, so a repository with a full page is refused.
+  listRepoAdvisories(options: { repo: RepoName }): Promise<any[]>
+  // Every page of `GET /user/repos`, as GitHub's repository objects; more
+  // than `maxPages` (100 by default) pages of 100 is an error.
+  listUserRepos(options?: { maxPages?: number }): Promise<any[]>
+}
+
+export function createClient(options: ClientOptions): Client

package/github.js

@@ -0,0 +1,2 @@
+export { createClient } from './src/github/read.js'
+export { HttpError } from './src/http.js'

package/npm.d.ts

@@ -0,0 +1,89 @@
+// 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
+// cache path, otherwise. Responses are read up to a size limit and within
+// a timeout, as github.d.ts describes, and lookups for many names go to
+// the registry eight at a time.
+
+// Where cached answers live, resolved when set. Unset by default, and
+// unset means no cache: every read misses and every write is skipped.
+//
+// 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 don't rely on this, since they
+// are checked against the registry's integrity on every call.
+export function setCacheDir(dir: string): void
+
+// 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 {
+  name: 'HttpError'
+  status: number
+}
+
+// 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.
+export interface GitHubLink {
+  github: string
+  directory?: string
+  url: string
+}
+export function getGitHub(name: string): Promise<GitHubLink>
+
+// What resolvePackageRepos maps each resolved name to.
+export interface PackageRepo {
+  github: string
+  directory?: string
+}
+// Fail-soft: a name that resolves to no repo is absent from the map.
+// `cachedOnly` answers from the disk cache alone and never fetches.
+export function resolvePackageRepos(packageNames: Iterable<string>, options?: { cachedOnly?: boolean }): Promise<Map<string, PackageRepo>>
+
+// The disk cache resolvePackageRepos reads and writes, a month per entry.
+// A read answers null for anything but a usable entry; a write answers
+// false where it could not write, and never throws.
+export function readPackageRepoCache(name: string): Promise<PackageRepo | null>
+export function writePackageRepoCache(name: string, github: string, directory?: string): Promise<boolean>
+
+// Where a published version's tarball is and what it hashes to: exactly
+// these two, `tarball` the registry's own URL for that version and
+// `integrity` one `sha512-<base64>`, nothing else (no sha1, second hash
+// or option). A dist given to a function below is held to the same.
+export interface Dist {
+  tarball: string
+  integrity: string
+}
+
+export interface PackageMeta {
+  name: string
+  version: string
+  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>
+
+// 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>
+
+// 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.
+//
+// Other tools' caches are read first, and never written: npm's (cacache
+// under npm_config_cache, else npm's default, `~/.npm` outside Windows;
+// and npm 4's `<name>/<version>/package.tgz` there), then
+// `~/.audit/cache/tgz/<org>:<name>-<version>.tgz`. A file there that does
+// not match is passed over. One in setCacheDir's cache that does not
+// match throws.
+export function getTarball(name: string, version: string, dist?: Dist): Promise<Uint8Array>

package/npm.js

@@ -0,0 +1,4 @@
+export { 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'

package/package.d.ts

@@ -0,0 +1,18 @@
+// 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
+  // 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.
+  directory?: string
+  // `https://github.com/<github>`, whenever there is a `github`.
+  url?: string
+}
+
+// Read off `bugs`, `repository` and `homepage`, in that order, from a
+// package.json or the registry's document for a version of one. Both
+// fields absent where nothing in it names a GitHub repo; a throw only
+// for something that is not an object at all.
+export function getRepo(pkg: object): PackageRepoLink

package/package.js

@@ -0,0 +1 @@
+export { getRepo } from './src/package.js'

package/package.json

@@ -0,0 +1,95 @@
+{
+  "name": "@preventive/upstream",
+  "version": "1.0.0-alpha.0",
+  "description": "Minimal npm registry and GitHub clients, and a git checkout reader: the calls we use, nothing more",
+  "type": "module",
+  "exports": {
+    "./advisories.js": {
+      "types": "./advisories.d.ts",
+      "default": "./advisories.js"
+    },
+    "./github.js": {
+      "types": "./github.d.ts",
+      "default": "./github.js"
+    },
+    "./github/write.js": {
+      "types": "./github/write.d.ts",
+      "default": "./github/write.js"
+    },
+    "./git.js": {
+      "types": "./git.d.ts",
+      "default": "./git.js"
+    },
+    "./npm.js": {
+      "types": "./npm.d.ts",
+      "default": "./npm.js"
+    },
+    "./package.js": {
+      "types": "./package.d.ts",
+      "default": "./package.js"
+    },
+    "./semver.js": {
+      "types": "./semver.d.ts",
+      "default": "./semver.js"
+    }
+  },
+  "files": [
+    "advisories.d.ts",
+    "advisories.js",
+    "github.d.ts",
+    "github.js",
+    "git.d.ts",
+    "git.js",
+    "github/write.d.ts",
+    "github/write.js",
+    "npm.d.ts",
+    "npm.js",
+    "package.d.ts",
+    "package.js",
+    "semver.d.ts",
+    "semver.js",
+    "src/advisories/common.js",
+    "src/advisories/github.js",
+    "src/advisories/index.js",
+    "src/advisories/npm.js",
+    "src/advisories/osv.js",
+    "src/advisories/repos.js",
+    "src/args.js",
+    "src/cache.js",
+    "src/git.js",
+    "src/github/client.js",
+    "src/github/read.js",
+    "src/github/write.js",
+    "src/http.js",
+    "src/npm/repos.js",
+    "src/npm/tarball.js",
+    "src/package.js",
+    "src/pool.js",
+    "src/remote.js",
+    "src/semver.js"
+  ],
+  "engines": {
+    "node": ">=24.14.0"
+  },
+  "scripts": {
+    "test": "node --test ./tests/*.test.js"
+  },
+  "license": "MIT",
+  "author": {
+    "name": "Nikita Skovoroda",
+    "email": "chalkerx@gmail.com",
+    "url": "https://github.com/ChALkeR"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/PreventiveMeasures/libraries.git",
+    "directory": "upstream"
+  },
+  "bugs": {
+    "url": "https://github.com/PreventiveMeasures/libraries/issues"
+  },
+  "homepage": "https://github.com/PreventiveMeasures/libraries/tree/main/upstream",
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/semver.d.ts

@@ -0,0 +1,11 @@
+// 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. Without it, every call throws, except valid() on a plain
+// MAJOR.MINOR.PATCH with no options.
+export function satisfies(version: string, range: string, options?: { includePrerelease?: boolean; loose?: boolean }): boolean
+export function compareVersions(a: string, b: string): -1 | 0 | 1
+// The version as semver spells it, or null: `v1.2.3` answers `1.2.3`.
+export function valid(version: unknown, options?: { loose?: boolean }): string | null
+// A string that valid() answers unchanged.
+export function isExactVersion(version: unknown): version is string

package/semver.js

@@ -0,0 +1 @@
+export { compareVersions, isExactVersion, satisfies, valid } from './src/semver.js'

package/src/advisories/common.js

@@ -0,0 +1,34 @@
+import { isStrings, matches } from '../args.js'
+import { satisfies, validRange } from '../semver.js'
+
+export const order = (a, b) => (a > b) - (a < b)
+
+// As `npm audit` matches: a prerelease is in a range around it.
+const SEMVER = { includePrerelease: true, loose: true }
+
+export const inRange = (version, range) => satisfies(version, range, SEMVER)
+
+// The asked versions a range `covers`. One semver cannot read covers them
+// all: a missed advisory is worse than a spare one.
+export const covered = (asked, range, covers = inRange) => (validRange(range, SEMVER) === null ? [...asked] : asked.filter((version) => covers(version, range)))
+
+// Remote text, as long as it is well-formed; anything else is refused as
+// malformed by whoever reads it.
+export const isText = (value) => typeof value === 'string' && value.isWellFormed()
+
+const SEVERITIES = new Set(['critical', 'high', 'moderate', 'low', 'info'])
+const isCvssVector = matches(/^CVSS:[34]\.\d(?:\/[A-Z]{1,4}:[A-Z]{1,2})+$/u)
+const isCwe = matches(/^CWE-\d{1,6}$/u)
+
+// The fields every source may carry, kept only in the shape they are
+// documented in: npm's severity words (GitHub's `medium` read `moderate`),
+// a score in (0, 10] (npm spells "not scored" 0), a CVSS vector, CWE ids.
+export function metrics({ severity, score, vector, cwe }) {
+  const word = typeof severity === 'string' ? severity.toLowerCase().replace(/^medium$/u, 'moderate') : undefined
+  return {
+    ...(SEVERITIES.has(word) && { severity: word }),
+    ...(typeof score === 'number' && score > 0 && score <= 10 && { cvss: score }),
+    ...(isCvssVector(vector) && { cvssVector: vector }),
+    cwe: isStrings(cwe) ? cwe.filter(isCwe) : [],
+  }
+}

package/src/advisories/github.js

@@ -0,0 +1,90 @@
+import assert from 'node:assert/strict'
+
+import { assertRepo, assertion, isGhsa, isRefName, isStrings } from '../args.js'
+import { isGone } from '../github/client.js'
+import { pool } from '../pool.js'
+import { valid } from '../semver.js'
+import { covered, inRange, isText, metrics } from './common.js'
+
+const REPOS_AT_ONCE = 4
+
+const isRepoAdvisory = (advisory) => advisory && typeof advisory === 'object' && isGhsa(advisory.ghsa_id)
+  && 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')
+
+const listAdvisories = (github, repo) => github.listRepoAdvisories({ repo }).catch((err) => {
+  if (isGone(err)) return []
+  throw err
+})
+
+// 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
+// semver cannot read, covers every version.
+function fromRepository(name, advisory, range, asked, covers) {
+  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,
+    aliases: [],
+    title: advisory.summary,
+    ...metrics({ severity: advisory.severity, score: cvss?.score, vector: cvss?.vector_string, cwe: advisory.cwe_ids }),
+    range,
+    versions: covered(asked, range.replaceAll(',', ' '), covers),
+  }
+}
+
+// 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
+// versions it `covers`.
+async function repositoryAdvisories(github, asked, { repoOf, takes = () => true, covers }) {
+  // 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 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(name, advisory, range, asked.get(name), covers))
+        }
+      }
+    }
+  }
+  return [...rows.values()]
+}
+
+// A maintainer's advisory is on the repository before GitHub reviews it
+// into the databases the registries answer from. With `repoAdvisories`,
+// 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 }, { 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 found = await lookUp([...asked.keys()].filter((name) => !known.has(name)))
+  const repoOf = (name) => known.get(name) ?? found.get(name)
+  const takes = (name, pkg) => pkg?.ecosystem === ecosystem && pkg.name === name
+  const added = await repositoryAdvisories(github, asked, { repoOf, takes, covers })
+  return [...rows, ...added.map((row) => ({ ...row, versions: row.versions.filter((version) => !reported.has(`${row.name} ${row.id} ${version}`)) }))]
+}
+
+// stasis versions a repository with no version of its own by its branch,
+// or 0.0.0: every range covers those. Whatever semver reads is a version,
+// `v1.2.3` and `1.2.3+build` included.
+const coversPlaceholder = (version, range) => version === '0.0.0' || valid(version) === null || inRange(version, range)
+
+// Dependencies that are GitHub repositories themselves: every range their
+// own published advisories list counts, whichever package it names.
+export const GITHUB = {
+  assertName: assertRepo,
+  assertVersion: assertion('a version or a branch name', isRefName),
+  advisories: (asked, { github }) => repositoryAdvisories(github, asked, { repoOf: (repo) => repo, covers: coversPlaceholder }),
+}