@preventive/upstream 1.0.0-alpha.10 → 1.0.0-alpha.11

package/advisories.d.ts

@@ -27,6 +27,19 @@ export interface Package {
   versions: string[]
 }
 
+// A store of the caller's, a database's say, for what would otherwise be
+// kept in setCacheDir's cache (npm.js): `read` answers the value last
+// written under `key`, or null or undefined for none. Keys are
+// `<kind>/<name>`, `github/advisories/owner/name` for a repository's
+// listing, and values plain JSON data, which `read` may answer as written
+// or as a copy. Whatever it answers is checked as a cached file is: one
+// malformed, stale or kept differently is a miss. A rejection from
+// either is the call's. It is trusted as setCacheDir's directory is.
+export interface CacheStore {
+  read(key: string): Promise<unknown>
+  write(key: string, value: unknown): Promise<void>
+}
+
 export interface AdvisoryOptions {
   // The client every GitHub request goes through. Required for `soldeer`
   // and `github` packages, whose repository's published advisories are
@@ -39,6 +52,9 @@ export interface AdvisoryOptions {
   // the one npm's metadata, crates.io or Packagist names, looked up
   // through the cache. Needs `github`.
   repoAdvisories?: boolean
+  // Where a repository's listing is kept, in place of setCacheDir's cache:
+  // see `advisories`. Repository lookups still go through that cache.
+  cache?: CacheStore
   // 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
@@ -108,6 +124,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 brotli-compressed at quality 9, or in
+// `cache` as it is. 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

@@ -32,10 +32,11 @@ 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, 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.
 export function setCacheDir(dir?: string | false): void
@@ -49,9 +50,9 @@ export class HttpError extends Error {
 
 // 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
@@ -73,7 +74,8 @@ export function resolvePackageRepos(packageNames: Iterable<string>, options?: {
 // release that resolved repos by other rules included; a write answers
 // 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.
+// 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>
 

package/package.d.ts

@@ -5,7 +5,10 @@ export interface PackageRepoLink {
   github?: string
   // Where in that repo the package sits, `/`-separated, as the tree path
   // itself (a homepage URL's decoded; a `repository.directory`'s `\` read
-  // as `/`); absent at its root, and whenever `github` is.
+  // 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.10",
+  "version": "1.0.0-alpha.11",
   "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": {

package/src/advisories/github.js

@@ -1,6 +1,7 @@
 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'
@@ -8,14 +9,65 @@ import { advisoryUrl, covered, detailsOf, isText, mayBeInRange, metrics } from '
 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 = 1
 
 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')
+export const assertCacheStore = assertion('a store with read and write', (value) => typeof value?.read === 'function' && typeof value?.write === 'function')
 
-const listAdvisories = (github, repo) => github.listRepoAdvisories({ repo }).catch(recover(isGone, []))
+// 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. 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, ...(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, store) {
+  const name = repo.toLowerCase()
+  const entry = await readRecord(DIR, name, { ttl: LISTING_TTL_MS, store })
+  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 }, { store })
+  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 +75,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 +92,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 }))
         }
       }
     }
@@ -74,12 +122,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 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 +141,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 +152,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), details, cache }),
 }

package/src/advisories/index.js

@@ -2,7 +2,7 @@ import assert from 'node:assert/strict'
 
 import { assertArgs, assertBoolean, assertRepo, assertion, isIterable, optional, sameName } from '../args.js'
 import { order } from './common.js'
-import { GITHUB, SOLDEER, assertClient } from './github.js'
+import { GITHUB, SOLDEER, assertCacheStore, assertClient } from './github.js'
 import { NPM } from './npm.js'
 import { CARGO, COMPOSER } from './osv.js'
 
@@ -34,7 +34,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(assertCacheStore) })
   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 +43,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/cache.js

@@ -3,12 +3,20 @@ import { constants } from 'node:fs'
 import { mkdir, open, rename, rm, writeFile } from 'node:fs/promises'
 import { homedir } from 'node:os'
 import { dirname, isAbsolute, join, resolve } from 'node:path'
+import { promisify } from 'node:util'
+import { brotliCompress, brotliDecompress, constants as zlib } from 'node:zlib'
 
 import { assertCacheName, assertDirectoryPath, isRepo } from './args.js'
 import { MAX_BYTES, decode } from './http.js'
 
-const DIRS = new Set(['npm/repos', 'npm/tarballs', 'cargo/repos', 'cargo/crates', 'composer/repos', 'soldeer/repos', 'soldeer/zips', 'github/trees'])
+const DIRS = new Set(['npm/repos', 'npm/tarballs', 'cargo/repos', 'cargo/crates', 'composer/repos', 'soldeer/repos', 'soldeer/zips', 'github/trees', 'github/advisories'])
 const RECORD_TTL_MS = 30 * 24 * 60 * 60 * 1000 // A link only moves on a transfer or rename, and GitHub redirects those.
+// Records filed brotli'd, at quality 9, as `<name>.json.br`: a listing
+// carries each advisory's full text, Markdown that compresses well.
+const BROTLI_DIRS = new Set(['github/advisories'])
+const BROTLI = { params: { [zlib.BROTLI_PARAM_QUALITY]: 9 } }
+const compress = promisify(brotliCompress)
+const decompress = promisify(brotliDecompress)
 
 // An environment variable may hold anything: only an absolute path is one.
 const absolute = (path) => (typeof path === 'string' && isAbsolute(path) ? path : undefined)
@@ -95,10 +103,12 @@ export async function readCache(dir, key) {
   return path && await readRegularFile(path)
 }
 
-export async function readCacheJSON(dir, key) {
+// With `brotli`, the file is decompressed first, to no more than a file
+// read; one that is not brotli, or runs past that, is a miss.
+export async function readCacheJSON(dir, key, { brotli = false } = {}) {
   const bytes = await readCache(dir, key)
   try {
-    return bytes && JSON.parse(decode(bytes, key))
+    return bytes && JSON.parse(decode(brotli ? await decompress(bytes, { maxOutputLength: MAX_BYTES }) : bytes, key))
   } catch {
     return null
   }
@@ -119,18 +129,31 @@ export async function writeCache(dir, key, data) {
   }
 }
 
-export async function writeCacheJSON(dir, key, value) {
-  return await writeCache(dir, key, JSON.stringify(value))
+export async function writeCacheJSON(dir, key, value, { brotli = false } = {}) {
+  const json = JSON.stringify(value)
+  return await writeCache(dir, key, brotli ? await compress(json, BROTLI) : json)
 }
 
-export async function readRecord(dir, name) {
-  const record = await readCacheJSON(dir, `${name}.json`)
+// A record is kept for `ttl`, in the cache set, or with `store`, in the
+// caller's store instead, under `<dir>/<name>`, as it is: only the files
+// are compressed.
+const recordFile = (dir, name) => (BROTLI_DIRS.has(dir) ? `${name}.json.br` : `${name}.json`)
+
+export async function readRecord(dir, name, { ttl = RECORD_TTL_MS, store } = {}) {
+  assert.ok(DIRS.has(dir), `Unexpected cache entry: ${dir}`)
+  const record = store ? await store.read(`${dir}/${name}`) : await readCacheJSON(dir, recordFile(dir, name), { brotli: BROTLI_DIRS.has(dir) })
   const age = typeof record?.at === 'number' ? Date.now() - record.at : Number.NaN
-  const fresh = age >= 0 && age <= RECORD_TTL_MS // An entry from the future is not fresh forever.
+  const fresh = age >= 0 && age <= ttl // An entry from the future is not fresh forever.
   return fresh && record.name === name ? record : null
 }
 
-export const writeRecord = (dir, name, value) => writeCacheJSON(dir, `${name}.json`, { at: Date.now(), name, ...value })
+export async function writeRecord(dir, name, value, { store } = {}) {
+  assert.ok(DIRS.has(dir), `Unexpected cache entry: ${dir}`)
+  const record = { at: Date.now(), name, ...value }
+  if (!store) return await writeCacheJSON(dir, recordFile(dir, name), record, { brotli: BROTLI_DIRS.has(dir) })
+  await store.write(`${dir}/${name}`, record)
+  return true
+}
 
 // Name → the GitHub repo cached for it, for those of `names` that have one.
 export async function readRepos(dir, names) {

package/src/git.js

@@ -54,5 +54,5 @@ export async function findGitCheckout(dir) {
   const directory = relative(dirs.root, start).split(sep).join('/')
   const github = await originGitHub(dirs.commonDir)
   const commit = await headCommit(dirs.gitDir, dirs.commonDir)
-  return { ...(github && { github }), ...(directory && { directory }), ...(github && { url: `https://github.com/${github}` }), ...(commit && { commit }) }
+  return { ...(github && { github }), directory, ...(github && { url: `https://github.com/${github}` }), ...(commit && { commit }) }
 }

package/src/npm/repos.js

@@ -1,6 +1,6 @@
 import assert from 'node:assert/strict'
 
-import { assertNames, assertPackageName, assertion, isRepo } from '../args.js'
+import { assertNames, assertPackageName, assertion, isRepo, optional } from '../args.js'
 import { readRecord, writeRecord } from '../cache.js'
 import { isNotFound, recover } from '../http.js'
 import { assertRepoDirectory, getRepo, isRepoDirectory } from '../package.js'
@@ -12,8 +12,10 @@ const CONCURRENCY = 8
 // Stamped on each entry, and raised when getRepo would answer differently:
 // 2 is `repository` taking precedence over `bugs`; 3 the shorthand dropping
 // a `.git`, URLs read past whitespace, and `repository.directory`'s `\` read
-// as `/`.
-const VERSION = 3
+// as `/`; 4 a declared root answered as `''`, no directory declared left
+// out (unknown) rather than read as the root, and a declared directory's
+// empty and `.` parts dropped.
+const VERSION = 4
 
 // A slug a lookup gives: getRepo answers no repo ending in `.git`, the
 // suffix it drops (withoutDotGit; `.GIT` it keeps, and so does this).
@@ -33,23 +35,23 @@ export async function getGitHub(name) {
 
 // An entry under another VERSION was resolved by other rules, and may
 // name a repo getRepo no longer would (a stale tracker's, or a shorthand's
-// with its `.git`): a miss, as is one naming a repo or a directory no
-// lookup gives, or without `directory`, which would read as a package at
-// the repo root.
+// with its `.git`, or the root where a package declared no directory): a
+// miss, as is one naming a repo or a directory no lookup gives. One without
+// `directory` is a package whose place in its repo is unknown.
 export async function readPackageRepoCache(name) {
   assertPackageName('readPackageRepoCache', 'name', name)
   const entry = await readRecord(DIR, name)
-  if (entry?.v !== VERSION || !isLookedUpRepo(entry.github) || !isRepoDirectory(entry.directory)) return null
-  return { github: entry.github, ...(entry.directory && { directory: entry.directory }) }
+  if (entry?.v !== VERSION || !isLookedUpRepo(entry.github) || (entry.directory !== undefined && !isRepoDirectory(entry.directory))) return null
+  return { github: entry.github, ...(entry.directory !== undefined && { directory: entry.directory }) }
 }
 
 // Only resolved repos are cached: a 404, a rate limit and a package with
 // no repo link fail alike.
-export async function writePackageRepoCache(name, github, directory = '') {
+export async function writePackageRepoCache(name, github, directory) {
   assertPackageName('writePackageRepoCache', 'name', name)
   assertLookedUpRepo('writePackageRepoCache', 'github', github)
-  assertRepoDirectory('writePackageRepoCache', 'directory', directory)
-  return await writeRecord(DIR, name, { v: VERSION, github, directory })
+  optional(assertRepoDirectory)('writePackageRepoCache', 'directory', directory)
+  return await writeRecord(DIR, name, { v: VERSION, github, ...(directory !== undefined && { directory }) })
 }
 
 export async function resolvePackageRepos(packageNames, options = {}) {
@@ -66,5 +68,5 @@ export async function lookUpPackageRepo(name) {
   const { github, directory } = await fetchRepo('lookUpPackageRepo', name).catch(recover(isNotFound, {}))
   if (!github) return null
   await writePackageRepoCache(name, github, directory)
-  return { github, ...(directory && { directory }) }
+  return { github, ...(directory !== undefined && { directory }) }
 }

package/src/package.js

@@ -38,8 +38,16 @@ function repoSubdirectory(value) {
 
 // `repository.directory` is a path its author may write with Windows' `\`.
 // A tree path is `/`-separated: a `\` is a name's own only in a homepage's
-// (`%5C`), which is the path itself.
-const declaredDirectory = (value) => repoSubdirectory(str(value).replaceAll('\\', '/'))
+// (`%5C`), which is the path itself. Its empty and `.` parts are dropped
+// (`./a//b/.` is `a/b`), and one of nothing else (`./`, `/`, `/.`, `.`, `''`)
+// declares the repo's root, `''`; one with a `..` part names none, whatever
+// it would come to. A package.json that declares none says nothing of where
+// in the repo it sits.
+function declaredDirectory(value) {
+  if (typeof value !== 'string') return undefined
+  const parts = value.replaceAll('\\', '/').split('/').filter((part) => part !== '' && part !== '.')
+  return parts.length === 0 ? '' : repoSubdirectory(parts.join('/'))
+}
 
 export const isRepoDirectory = (value) => typeof value === 'string' && (value === '' || repoSubdirectory(value) === value)
 export const assertRepoDirectory = assertion('a path inside the repository', isRepoDirectory)
@@ -54,7 +62,7 @@ export function getRepo(pkg) {
   // `bugs` tracker can be left pointing at a former owner or misspelt.
   const github = [declared, repoIn(bugsRegex, urlOf(bugs)), homepageRepo].find(isRepo)
   if (github === undefined) return {}
-  const directory = (sameName(declared, github) && declaredDirectory(repository?.directory))
-    || (sameName(homepageRepo, github) && repoSubdirectory(decodePath(homepage.directory)))
-  return { github, ...(directory && { directory }), url: `https://github.com/${github}` }
+  const directory = (sameName(declared, github) ? declaredDirectory(repository?.directory) : undefined)
+    ?? (sameName(homepageRepo, github) ? repoSubdirectory(decodePath(homepage.directory)) : undefined)
+  return { github, ...(directory !== undefined && { directory }), url: `https://github.com/${github}` }
 }