@preventive/triage 1.0.0-alpha.5 → 1.0.0-alpha.50

package/server-managed/repository-browser.ts

@@ -0,0 +1,294 @@
+import { createHash } from 'node:crypto'
+import type { ManagedConfig } from './config.ts'
+import type { SelectedRepo } from './db.ts'
+import { GithubApiError, type GithubIdentity, READ_PERMISSIONS, githubJson, githubRepoPermission, githubUserIdentity, onTokenRejected, repoAccessToken } from './github-app.ts'
+import { MAX_PACKAGE_BYTES, readPackageEntryPoints } from './package-entry-points.ts'
+import { readSolidityEntryPoints } from './solidity-entry-points.ts'
+import { parseGithubCommit } from './bundle-commits.ts'
+import { appDependabotAlerts } from './dependabot-access.ts'
+
+const REFS_PAGE = 100
+
+// Each branch or tag GitHub lists, by its name and commit, those it names
+// one for.
+const refCommits = (items: { name?: unknown; commit?: { sha?: unknown } }[]) => items.flatMap(item => typeof item?.name === 'string' && item.name
+  && typeof item.commit?.sha === 'string' && /^[a-f\d]{40}$/u.test(item.commit.sha) ? [{ name: item.name, sha: item.commit.sha }] : [])
+
+// Each branch GitHub lists, by its name and commit. Branches are listed by
+// name, a full page of them leaving the default branch out where many come
+// before it: its commit is read apart then, by its ref, none where that fails.
+async function branchCommits(read: (suffix: string) => Promise<unknown>, branches: { name?: unknown; commit?: { sha?: unknown } }[], defaultBranch: string) {
+  const listed = refCommits(branches)
+  if (!defaultBranch || branches.length < REFS_PAGE || listed.some(item => item.name === defaultBranch)) return listed
+  const ref = await read(`/git/ref/heads/${defaultBranch.split('/').map(encodeURIComponent).join('/')}`).catch(() => null) as { object?: { sha?: unknown } } | null
+  return typeof ref?.object?.sha === 'string' && /^[a-f\d]{40}$/u.test(ref.object.sha) ? [...listed, { name: defaultBranch, sha: ref.object.sha }] : listed
+}
+
+export interface RepositoryEntry { name: string; path: string; type: 'dir' | 'file' | 'symlink' | 'submodule' }
+
+// Restricted managers can walk the ancestors of their grants, without seeing
+// sibling names or files outside those grants. null means the entire repo.
+export function scopedDirectory(path: string, scopes: (string | null)[]): RepositoryEntry[] | null {
+  if (scopes.some(scope => !scope || path === scope || path.startsWith(scope + '/'))) return null
+  const prefix = path ? path + '/' : ''
+  const names = new Set(scopes.filter((scope): scope is string => !!scope && scope.startsWith(prefix)).map(scope => scope.slice(prefix.length).split('/')[0]!))
+  return [...names].toSorted().map(name => ({ name, path: prefix + name, type: 'dir' }))
+}
+
+export interface RepositoryBrowserUser { githubUserId: number | null; token: string | null }
+
+function credentialFailure(err: unknown): err is GithubApiError {
+  return err instanceof GithubApiError && ([401, 404].includes(err.status) || err.message === 'github-status-403')
+}
+
+// GitHub's answer on a user's access to a repository, as checkAccess reads it:
+// the repository's metadata, which credential reads it (the user's token, the
+// App installation's, or none, as for a public repository read anonymously)
+// and the permission level GitHub told, where it was asked. Kept per user, by
+// their GitHub id and token, and per repository, by its id, name and
+// installation, for config.repositoryAccessCacheMs; only access granted is kept.
+// One answered for a user with a token is kept no longer once GitHub rejects
+// that token (`userToken`, hashed), whichever credential reads it: a private
+// repository's was granted on who that token told GitHub they are. The next
+// check asks GitHub, falling back to the installation's or none as it does.
+type RepoMetadata = { id?: unknown; full_name?: unknown; private?: unknown; visibility?: unknown; default_branch?: unknown }
+type AccessVerdict = { until: number; data: RepoMetadata; credential: 'user' | 'app' | 'none'; level: string | null; userToken: string | null }
+type VerdictCache = { get(): AccessVerdict | undefined; set(verdict: Omit<AccessVerdict, 'until' | 'userToken'>): void }
+const MAX_ACCESS_VERDICTS = 1000
+// By the fetch reading GitHub, as installation tokens are: a test's own.
+const accessVerdicts = new WeakMap<typeof fetch, Map<string, AccessVerdict>>()
+const hashed = (token: string) => createHash('sha256').update(token).digest('hex')
+onTokenRejected((token, fetchImpl) => {
+  const kept = accessVerdicts.get(fetchImpl)
+  if (!kept) return
+  const rejected = hashed(token)
+  for (const [key, verdict] of kept) if (verdict.userToken === rejected) kept.delete(key)
+})
+
+function verdictCache(config: ManagedConfig, user: RepositoryBrowserUser, repo: SelectedRepo, fetchImpl: typeof fetch): VerdictCache | null {
+  const keepMs = config.repositoryAccessCacheMs
+  if (!(keepMs > 0)) return null
+  let verdicts = accessVerdicts.get(fetchImpl)
+  if (!verdicts) { verdicts = new Map(); accessVerdicts.set(fetchImpl, verdicts) }
+  const kept = verdicts
+  // The token hashed with the rest, never kept as it is.
+  const key = createHash('sha256').update(JSON.stringify([user.githubUserId, user.token, repo.repoId, repo.fullName.toLowerCase(), repo.installationId, config.githubAppId])).digest('hex')
+  return {
+    get() {
+      const verdict = kept.get(key)
+      if (verdict && verdict.until > Date.now()) return verdict
+      kept.delete(key)
+      return undefined
+    },
+    set(verdict) {
+      kept.delete(key)
+      kept.set(key, { ...verdict, until: Date.now() + keepMs, userToken: user.token ? hashed(user.token) : null })
+      while (kept.size > MAX_ACCESS_VERDICTS) kept.delete(kept.keys().next().value!)
+    },
+  }
+}
+
+// Create once per HTTP request. Coalesce concurrent credential lookups, and
+// keep GitHub's answer on each user's access to each repository a while
+// (verdictCache), never sharing credentials or answers across users.
+export function createRepositoryBrowser(config: ManagedConfig, user: RepositoryBrowserUser, fetchImpl: typeof fetch = globalThis.fetch) {
+  const tokens = new Map<number, Promise<string | null>>()
+  let identity: Promise<GithubIdentity> | undefined
+  // The user as GitHub tells them, asked once a request.
+  const getIdentity = (): Promise<GithubIdentity> => {
+    if (!user.token || user.githubUserId == null) return Promise.reject(new GithubApiError(404, 'no-repository'))
+    if (!identity) {
+      identity = githubUserIdentity(user.token, fetchImpl).then(value => {
+        if (value.id !== user.githubUserId) throw new GithubApiError(404, 'no-repository')
+        return value
+      })
+    }
+    return identity
+  }
+  return {
+    reader(repo: SelectedRepo) {
+      const installationToken = () => {
+        if (repo.installationId == null) return Promise.resolve(null)
+        const cached = tokens.get(repo.installationId)
+        const token = cached ?? repoAccessToken(config, repo.installationId, fetchImpl).catch((err: unknown) => {
+          if (!credentialFailure(err)) throw err
+          // Stale installations cannot prevent verified public access.
+          return null
+        })
+        if (!cached) tokens.set(repo.installationId, token)
+        return token
+      }
+      // Its Dependabot alerts, with the token of the installation GitHub tells
+      // covers it, where the user's own access lets them see them
+      // (dependabot-access.ts).
+      return repositoryReader(repo, user.token, installationToken, getIdentity, fetchImpl, verdictCache(config, user, repo, fetchImpl)).then(reader => ({ ...reader,
+        dependabotAlerts: () => appDependabotAlerts(config, repo, { identity: getIdentity, permission: reader.permission }, fetchImpl) }))
+    },
+  }
+}
+
+// The files of the tree `tree` (its id) of the repository `fullName`, and of
+// every tree under it, as GitHub lists them at once with `token`, a reader's
+// (readToken): how many and their bytes, or null where GitHub cuts the
+// listing short, as it does past 100,000 entries.
+export async function repositoryTreeFiles(fullName: string, token: string | null, tree: string, fetchImpl: typeof fetch = globalThis.fetch) {
+  if (!/^[a-f\d]{40}$/u.test(tree)) throw new GithubApiError(400, 'bad-tree')
+  const url = `https://api.github.com/repos/${fullName.split('/').map(encodeURIComponent).join('/')}/git/trees/${tree}?recursive=1`
+  const data = await githubJson(url, token, fetchImpl) as { tree?: unknown; truncated?: unknown }
+  if (!Array.isArray(data?.tree)) throw new GithubApiError(502, 'github-malformed')
+  if (data.truncated === true) return null
+  let bytes = 0, files = 0
+  for (const item of data.tree as { type?: unknown; size?: unknown }[]) {
+    if (item?.type !== 'blob') continue
+    files++
+    if (typeof item.size === 'number' && item.size > 0) bytes += item.size
+  }
+  return { files, bytes }
+}
+
+type Access = { data: RepoMetadata; token: string | null; level: string | null }
+
+// GitHub asked whether the user may read `repo`: its metadata, read with
+// `token` (the reader's credential so far), else the installation's, else
+// none; and of one not public, the user's permission, read with the
+// installation's. What it told, the token reading it, and the level asked.
+async function askAccess(repo: SelectedRepo, start: string | null, userToken: string | null, installationToken: () => Promise<string | null>,
+  getIdentity: () => Promise<GithubIdentity>, fetchImpl: typeof fetch): Promise<Access> {
+  const base = `https://api.github.com/repos/${repo.fullName.split('/').map(encodeURIComponent).join('/')}`
+  let token = start
+  const metadata = async () => {
+    try { return await githubJson(base, token, fetchImpl) }
+    catch (err) {
+      if (!token || !credentialFailure(err)) throw err
+      const fallback = await installationToken()
+      if (fallback && fallback !== token) {
+        token = fallback
+        try { return await githubJson(base, token, fetchImpl) } catch (fallbackError) { if (!credentialFailure(fallbackError)) throw fallbackError }
+      }
+      // Anonymous fallback is only for unavailable credentials, never rate
+      // limits, network errors, or GitHub outages.
+      token = null
+      return githubJson(base, token, fetchImpl)
+    }
+  }
+  // A repository last known private asks who the user is, and mints the
+  // installation token its permission is asked with, as it asks for its
+  // metadata, not after. Each is asked once a request (the token once for
+  // concurrent requests too, github-app.ts), so a failure is answered where
+  // it is awaited. One made public since mints a token it never waits for,
+  // kept for later requests.
+  if (repo.private && userToken) {
+    getIdentity().catch(() => {})
+    if (repo.installationId != null) installationToken().catch(() => {})
+  }
+  // Stored visibility can be stale (or internal with private=false). Require
+  // current, explicit public visibility or the caller's effective permission.
+  const data = await metadata() as RepoMetadata
+  if (data?.id !== repo.repoId || typeof data.full_name !== 'string' || data.full_name.toLowerCase() !== repo.fullName.toLowerCase()) {
+    throw new GithubApiError(404, 'no-repository')
+  }
+  if (data.private === false && data.visibility === 'public') return { data, token, level: null }
+  if (!token) throw new GithubApiError(404, 'no-repository')
+  const appToken = await installationToken()
+  if (!appToken) throw new GithubApiError(404, 'no-repository')
+  const level = await githubRepoPermission(repo.fullName, appToken, await getIdentity(), fetchImpl)
+  if (!READ_PERMISSIONS.has(level)) throw new GithubApiError(404, 'no-repository')
+  return { data, token: appToken, level }
+}
+
+// GitHub's answer as kept (verdictCache), with the credential it chose,
+// where that credential is still had; else asked (`ask`), and kept where it
+// grants access.
+async function keptAccess(verdicts: VerdictCache | null, userToken: string | null, installationToken: () => Promise<string | null>,
+  ask: () => Promise<Access>): Promise<Access> {
+  const kept = verdicts?.get()
+  if (kept) {
+    const credential = kept.credential === 'user' ? userToken : kept.credential === 'app' ? await installationToken() : null
+    if (kept.credential === 'none' || credential) return { data: kept.data, token: credential, level: kept.level }
+  }
+  const asked = await ask()
+  const { id, full_name, private: hidden, visibility, default_branch } = asked.data
+  const data = { id, full_name, private: hidden, visibility, default_branch }
+  verdicts?.set({ data, credential: asked.token === null ? 'none' : asked.token === userToken ? 'user' : 'app', level: asked.level })
+  return { ...asked, data }
+}
+
+async function repositoryReader(repo: SelectedRepo, userToken: string | null, installationToken: () => Promise<string | null>, getIdentity: (fresh?: boolean) => Promise<GithubIdentity>, fetchImpl: typeof fetch,
+  verdicts: VerdictCache | null) {
+  const base = `https://api.github.com/repos/${repo.fullName.split('/').map(encodeURIComponent).join('/')}`
+  // Public reads can use the signed-in user's quota without repository grants.
+  // Nonpublic reads still require the repository App and the effective-user gate,
+  // whose permission level is kept (`level`).
+  let level: string | null = null, token = userToken ?? await installationToken()
+  const read = (suffix: string) => githubJson(base + suffix, token, fetchImpl)
+  const checkAccess = async (): Promise<RepoMetadata> => {
+    const access = await keptAccess(verdicts, userToken, installationToken, () => askAccess(repo, token, userToken, installationToken, getIdentity, fetchImpl))
+    token = access.token
+    level = access.level
+    return access.data
+  }
+  const current = await checkAccess()
+  const defaultBranch = typeof current.default_branch === 'string' ? current.default_branch : ''
+  return {
+    // Its visibility and the user's permission asked again, the user as
+    // GitHub told them earlier in the request, not asked again.
+    recheckAccess: () => checkAccess(),
+    // Server-only credential, selected by the same live visibility/permission
+    // gate as directory browsing. Never included in an HTTP response.
+    readToken: () => token,
+    // The user's permission level on it where the gate asked GitHub of it, as
+    // for a private repository; null for a public one.
+    permission: () => level,
+    // Its default branch as GitHub named it when access was first checked,
+    // `''` where it named none: the one whose head `commit('')` reads.
+    defaultBranch,
+    async refs() {
+      // Suggestions are bounded; the input also accepts any branch or tag name.
+      const list = async (kind: string) => {
+        const data = await read(`/${kind}?per_page=${REFS_PAGE}`)
+        if (!Array.isArray(data)) throw new GithubApiError(502, 'github-malformed')
+        return data
+      }
+      const [branches, tags] = await Promise.all([list('branches'), list('tags')])
+      const names = (items: { name?: unknown }[]) => items.flatMap(item => typeof item?.name === 'string' ? [item.name] : [])
+      // Each branch's and tag's commit, for the code viewer's header to name a
+      // commit by, and each tag's for the tag cache. A full page may leave
+      // tags out; only a shorter one lists every tag.
+      return { defaultBranch, branches: names(branches), tags: names(tags), branchCommits: await branchCommits(read, branches, defaultBranch),
+        tagCommits: refCommits(tags), tagsComplete: tags.length < REFS_PAGE }
+    },
+    async commit(ref: string) {
+      if (/^[a-f\d]{40}$/iu.test(ref)) return ref
+      const data = await read(`/commits/${encodeURIComponent(ref || (defaultBranch ? `heads/${defaultBranch}` : 'HEAD'))}`) as { sha?: unknown }
+      if (typeof data?.sha !== 'string' || !/^[a-f\d]{40}$/iu.test(data.sha)) throw new GithubApiError(502, 'github-malformed')
+      return data.sha
+    },
+    // The first commit a listing from `sha` returns is that commit, without
+    // the files GET /commits/:sha adds.
+    async commitDetails(sha: string) {
+      return /^[a-f\d]{40}$/u.test(sha) ? parseGithubCommit(sha, await read(`/commits?sha=${sha}&per_page=1`)) : null
+    },
+    async directory(path: string, commit: string) {
+      const data = await read(`/contents/${path.split('/').map(encodeURIComponent).join('/')}?ref=${encodeURIComponent(commit)}`)
+      if (!Array.isArray(data)) throw new GithubApiError(400, 'not-a-directory')
+      const entries: RepositoryEntry[] = []
+      for (const item of data) {
+        if (typeof item?.name !== 'string' || item.name.includes('/') || item.name === '.' || item.name === '..') continue
+        const expectedPath = path ? `${path}/${item.name}` : item.name
+        if (item.path !== expectedPath) continue
+        const type = item.submodule_git_url ? 'submodule' : item.type
+        if (['dir', 'file', 'symlink', 'submodule'].includes(type)) entries.push({ name: item.name, path: expectedPath, type })
+      }
+      const manifestPath = path ? `${path}/package.json` : 'package.json'
+      const manifest = data.find(item => item?.path === manifestPath && item.name === 'package.json' && item.type === 'file' && !item.submodule_git_url
+        && typeof item.size === 'number' && item.size >= 0 && item.size <= MAX_PACKAGE_BYTES && typeof item.sha === 'string' && /^[a-f\d]{40}$/iu.test(item.sha))
+      // Both optional suggestions, read together: neither fails, each
+      // answering none where its reads do.
+      const [packageEntryPoints, solidity] = await Promise.all([manifest ? readPackageEntryPoints(manifest.sha, path, read) : undefined,
+        readSolidityEntryPoints(path, data, read)])
+      return { entries, limited: data.length >= 1000, ...(packageEntryPoints ? { packageEntryPoints } : {}),
+        ...(solidity.paths.length > 0 || solidity.limited ? { solidityEntryPoints: solidity.paths, soliditySuggestionsLimited: solidity.limited } : {}),
+      }
+    },
+  }
+}

package/server-managed/repository-changes.ts

@@ -0,0 +1,284 @@
+// The files each commit changes, as the code viewer's Replay plays them
+// (GET /api/admin/repositories/changes), as `git log --name-status` lists
+// them: each file's path and whether the commit added (`A`), modified (`M`),
+// removed (`D`) or renamed (`R`, with the path it had) it, as GitHub's REST
+// API lists a commit's files (GET /repos/:owner/:repo/commits/:sha), a
+// page of FILES_PAGE at a time, as many as MAX_FILES, `more` where it had
+// more. What a commit changes never changes, so each is kept by the commit
+// (`kept`), whole, read of GitHub once; what a reader is answered, only the
+// files within the directory they asked of (changesWithin). And the files a
+// commit holds, which Replay starts from (GET /api/admin/repositories/tree),
+// as GitHub lists its tree at once (repositoryTree), kept as well.
+
+import { GithubApiError, githubJson } from './github-app.ts'
+
+// Commits an answer tells at most, read of GitHub as many at once as
+// CHANGES_PARALLEL.
+export const CHANGES_ASKED = 50
+const CHANGES_PARALLEL = 6
+// A commit's files read, as many as fill MAX_FILES, FILES_PAGE a page (the
+// most GitHub lists a page; it lists fewer, unasked).
+export const MAX_FILES = 300
+export const FILES_PAGE = 100
+const MAX_PATH = 4096
+const SHA = /^[a-f\d]{40}$/u
+
+export type ChangeStatus = 'A' | 'M' | 'D' | 'R'
+// A file a commit changes: its path, its status, and a rename's path before.
+export type ChangedFile = [path: string, status: Exclude<ChangeStatus, 'R'>] | [path: string, status: 'R', from: string]
+export interface CommitChanges { files: ChangedFile[]; more: boolean }
+
+// What each commit changes kept, by the commit.
+export interface ChangesStore {
+  read(shas: string[]): Promise<Map<string, CommitChanges>>
+  write(sha: string, changes: CommitChanges): Promise<void>
+}
+
+const pathOf = (value: unknown) => typeof value === 'string' && value !== '' && value.length <= MAX_PATH && !/\p{Cc}/u.test(value) ? value : null
+
+// A file's status as git names it: a copy is a file added; one GitHub
+// lists unchanged (its mode alone changed, say) changes none.
+const STATUSES: Record<string, ChangeStatus> = { added: 'A', copied: 'A', modified: 'M', changed: 'M', removed: 'D', renamed: 'R' }
+
+type GithubFile = { filename?: unknown; status?: unknown; previous_filename?: unknown }
+
+// A commit's files as GitHub lists them; a rename it names no path before
+// for, a file added.
+export function commitChanges(data: unknown): CommitChanges {
+  const listed = (data as { files?: unknown } | null)?.files
+  if (!Array.isArray(listed)) throw new GithubApiError(502, 'github-malformed')
+  const files = (listed as GithubFile[]).slice(0, MAX_FILES).flatMap((file): ChangedFile[] => {
+    const path = pathOf(file?.filename)
+    const status = typeof file?.status === 'string' ? STATUSES[file.status] : undefined
+    if (!path || !status) return []
+    const from = status === 'R' ? pathOf(file.previous_filename) : null
+    return [status === 'R' ? from ? [path, 'R', from] : [path, 'A'] : [path, status]]
+  })
+  return { files, more: listed.length >= MAX_FILES }
+}
+
+// What a commit changes within the directory `path` ('' the whole
+// repository): its files there, a rename across its edge the file added
+// where it came in, removed where it went out.
+export function changesWithin({ files, more }: CommitChanges, path: string): CommitChanges {
+  if (path === '') return { files, more }
+  const within = (file: string) => file.startsWith(`${path}/`)
+  return { more, files: files.flatMap((file): ChangedFile[] => {
+    if (file[1] !== 'R') return within(file[0]) ? [file] : []
+    const [to, , from] = file
+    if (within(to)) return [within(from) ? file : [to, 'A']]
+    return within(from) ? [[from, 'D']] : []
+  }) }
+}
+
+// Runs `run` for each of `items`, as many at once as `parallel`.
+async function eachOf<T>(items: T[], parallel: number, run: (item: T) => Promise<void>) {
+  let next = 0
+  await Promise.all(Array.from({ length: Math.min(parallel, items.length) }, async () => { while (next < items.length) await run(items[next++]!) }))
+}
+
+// A commit's files as GitHub lists them, read a page at a time while each
+// is full, till MAX_FILES are.
+async function commitFiles(url: string, token: string | null, fetchImpl: typeof fetch) {
+  const files: unknown[] = []
+  for (let page = 1; files.length < MAX_FILES; page++) {
+    const data = await githubJson(`${url}?per_page=${FILES_PAGE}&page=${page}`, token, fetchImpl) as { files?: unknown } | null
+    if (!Array.isArray(data?.files)) throw new GithubApiError(502, 'github-malformed')
+    files.push(...data.files)
+    if (data.files.length < FILES_PAGE) break
+  }
+  return { files }
+}
+
+// What each of `shas` changes, kept, else read of GitHub and then kept; null
+// for one GitHub has no commit of (as one of another repository is).
+export async function repositoryChanges(fullName: string, token: string | null, shas: string[], kept: ChangesStore,
+  fetchImpl: typeof fetch = globalThis.fetch): Promise<Map<string, CommitChanges | null>> {
+  const asked = [...new Set(shas)].filter(sha => SHA.test(sha))
+  const found = new Map<string, CommitChanges | null>(await kept.read(asked))
+  const repo = `https://api.github.com/repos/${fullName.split('/').map(encodeURIComponent).join('/')}`
+  await eachOf(asked.filter(sha => !found.has(sha)), CHANGES_PARALLEL, async sha => {
+    try {
+      const changes = commitChanges(await commitFiles(`${repo}/commits/${sha}`, token, fetchImpl))
+      found.set(sha, changes)
+      await kept.write(sha, changes)
+    } catch (err) {
+      // No such commit: GitHub's 404, or its 422 for an id naming none.
+      if (err instanceof GithubApiError && (err.message === 'github-not-found' || err.message === 'github-status-422')) found.set(sha, null)
+      else throw err
+    }
+  })
+  return new Map(asked.map(sha => [sha, found.get(sha) ?? null]))
+}
+
+// The files a commit (or a tree) holds, as many as MAX_TREE_FILES, each by its path and
+// its bytes (`sizes`, in the same order), as
+// GitHub lists its tree and every tree under it at once
+// (GET /repos/:owner/:repo/git/trees/:tree?recursive=1); where GitHub cuts
+// that listing short (past 100,000 entries or 7 MB, as a large repository's
+// is), as GitHub advises: the tree's own entries listed alone, and each tree
+// in it read so in turn, as many at once as TREES_PARALLEL (treeByTrees).
+// Its blobs, not its directories nor submodules, sorted by path; past
+// MAX_TREE_FILES those nearest its root of those read, `cut` where some are
+// left out: more files than MAX_TREE_FILES, a tree's own entries cut short,
+// or more trees to read than MAX_TREE_READS.
+// Null for a commit GitHub has none of. Kept by the commit and the rules it
+// is read by (TREES_READ), a tree kept by older ones (without sizes, the
+// last) read again.
+export const MAX_TREE_FILES = 75_000
+export const TREES_READ = 3
+const MAX_TREE_READS = 400
+const TREES_PARALLEL = 6
+export interface CommitTree { files: string[]; sizes: number[]; cut: boolean }
+export interface TreeStore {
+  read(commit: string): Promise<CommitTree | null>
+  write(commit: string, tree: CommitTree): Promise<void>
+}
+
+type TreeEntry = { type?: unknown; path?: unknown; sha?: unknown; size?: unknown }
+// A file read: its path and its bytes.
+type Blob = [path: string, size: number]
+type TreeListing = (tree: string, recursive: boolean) => Promise<{ entries: TreeEntry[]; truncated: boolean }>
+
+export async function repositoryTree(fullName: string, token: string | null, commit: string, kept: TreeStore,
+  fetchImpl: typeof fetch = globalThis.fetch): Promise<CommitTree | null> {
+  if (!SHA.test(commit)) return null
+  const held = await kept.read(commit)
+  if (held) return held
+  const repo = `https://api.github.com/repos/${fullName.split('/').map(encodeURIComponent).join('/')}`
+  const listing: TreeListing = async (tree, recursive) => {
+    const data = await githubJson(`${repo}/git/trees/${tree}${recursive ? '?recursive=1' : ''}`, token, fetchImpl) as { tree?: unknown; truncated?: unknown }
+    if (!Array.isArray(data?.tree)) throw new GithubApiError(502, 'github-malformed')
+    return { entries: data.tree as TreeEntry[], truncated: data.truncated === true }
+  }
+  let whole: Awaited<ReturnType<TreeListing>>
+  try {
+    whole = await listing(commit, true)
+  } catch (err) {
+    if (err instanceof GithubApiError && (err.message === 'github-not-found' || err.message === 'github-status-422')) return null
+    throw err
+  }
+  const files: Blob[] = []
+  let cut = false
+  if (whole.truncated) cut = await treeByTrees(commit, listing, files)
+  else blobsOf(whole.entries, '', files)
+  const depth = (path: string) => path.split('/').length
+  const byPath = ([a]: Blob, [b]: Blob) => a < b ? -1 : a > b ? 1 : 0
+  const nearest = files.length > MAX_TREE_FILES ? files.toSorted((a, b) => depth(a[0]) - depth(b[0]) || byPath(a, b)).slice(0, MAX_TREE_FILES) : files
+  const sorted = nearest.toSorted(byPath)
+  const tree = { files: sorted.map(([path]) => path), sizes: sorted.map(([, size]) => size), cut: cut || files.length > MAX_TREE_FILES }
+  await kept.write(commit, tree)
+  return tree
+}
+
+// The blobs of a tree's entries, each its path under `prefix` and its bytes
+// (none, as GitHub names none), onto `files`.
+function blobsOf(entries: TreeEntry[], prefix: string, files: Blob[]) {
+  for (const item of entries) {
+    if (item?.type !== 'blob' || !pathOf(item.path)) continue
+    files.push([`${prefix}${item.path as string}`, Number.isSafeInteger(item.size) && (item.size as number) > 0 ? item.size as number : 0])
+  }
+}
+
+// The files under the commit's tree, `commit`, onto `files`, its trees read
+// a round at a time, those nearest the root first: its own entries, then
+// each tree in it whole, or, where that is cut short, alone in turn, and so
+// on. Each round read whole, whatever answers first, but for trees no file
+// of which could be kept: as deep as, or deeper than, the files nearest the
+// root, as many as MAX_TREE_FILES, of those read (files of a tree are at
+// least a level deeper than it is). As many trees read in all as
+// MAX_TREE_READS, those of a round first in its order. Whether some were
+// left out.
+async function treeByTrees(commit: string, listing: TreeListing, files: Blob[]): Promise<boolean> {
+  let cut = false, reads = 1, round = [{ tree: commit, prefix: '', recursive: false }]
+  const atDepth: number[] = []
+  let counted = 0
+  while (round.length > 0) {
+    for (; counted < files.length; counted++) {
+      const depth = files[counted]![0].split('/').length
+      atDepth[depth] = (atDepth[depth] ?? 0) + 1
+    }
+    // The depth no file deeper than is kept.
+    let kept = Number.POSITIVE_INFINITY
+    for (let depth = 0, sum = 0; depth < atDepth.length; depth++) {
+      sum += atDepth[depth] ?? 0
+      if (sum >= MAX_TREE_FILES) {
+        kept = depth
+        break
+      }
+    }
+    const asked = round.filter(({ prefix }) => prefix.split('/').length - 1 < kept).slice(0, Math.max(0, MAX_TREE_READS - reads))
+    cut ||= asked.length < round.length
+    reads += asked.length
+    const listed: Awaited<ReturnType<TreeListing>>[] = []
+    await eachOf([...asked.keys()], TREES_PARALLEL, async at => { listed[at] = await listing(asked[at]!.tree, asked[at]!.recursive) })
+    const next: typeof round = []
+    for (const [at, { tree, prefix, recursive }] of asked.entries()) {
+      const { entries, truncated } = listed[at]!
+      if (truncated && recursive) {
+        next.push({ tree, prefix, recursive: false })
+        continue
+      }
+      cut ||= truncated
+      blobsOf(entries, prefix, files)
+      if (recursive) continue
+      for (const item of entries) {
+        const path = pathOf(item?.path)
+        if (item?.type === 'tree' && path && typeof item.sha === 'string' && SHA.test(item.sha)) next.push({ tree: item.sha, prefix: `${prefix}${path}/`, recursive: true })
+      }
+    }
+    round = next
+  }
+  return cut
+}
+
+// The files commit `commit` holds within the directory `path` ('' the whole
+// repository), as repositoryTree reads them: its whole tree's within it; where
+// that is cut short, some of the directory's perhaps among those left out,
+// the directory's own tree read so (directoryTree), kept by its id, the files
+// nearest it kept. Null for a commit GitHub has none of.
+export async function directoryFiles(fullName: string, token: string | null, commit: string, path: string, kept: TreeStore,
+  fetchImpl: typeof fetch = globalThis.fetch): Promise<CommitTree | null> {
+  const whole = await repositoryTree(fullName, token, commit, kept, fetchImpl)
+  if (!whole || path === '' || !whole.cut) return whole && treeWithin(whole, path)
+  const id = await directoryTree(fullName, token, commit, path, fetchImpl)
+  const own = id ? await repositoryTree(fullName, token, id, kept, fetchImpl) : null
+  return own ? { ...own, files: own.files.map(file => `${path}/${file}`) } : treeWithin(whole, path)
+}
+
+// The id of the tree at `path` in commit `commit`, read a level at a time
+// (GET /repos/:owner/:repo/git/trees/:tree, its own entries alone); null
+// where it has none there, or GitHub has no such commit.
+async function directoryTree(fullName: string, token: string | null, commit: string, path: string, fetchImpl: typeof fetch): Promise<string | null> {
+  const repo = `https://api.github.com/repos/${fullName.split('/').map(encodeURIComponent).join('/')}`
+  let tree = commit
+  for (const name of path.split('/')) {
+    let data: { tree?: unknown }
+    try {
+      data = await githubJson(`${repo}/git/trees/${tree}`, token, fetchImpl) as typeof data
+    } catch (err) {
+      if (err instanceof GithubApiError && (err.message === 'github-not-found' || err.message === 'github-status-422')) return null
+      throw err
+    }
+    if (!Array.isArray(data?.tree)) throw new GithubApiError(502, 'github-malformed')
+    const entry = (data.tree as TreeEntry[]).find(item => item?.path === name && item.type === 'tree')
+    if (typeof entry?.sha !== 'string' || !SHA.test(entry.sha)) return null
+    tree = entry.sha
+  }
+  return tree
+}
+
+// The files of a tree within the directory `path` ('' the whole repository).
+export function treeWithin({ files, sizes, cut }: CommitTree, path: string): CommitTree {
+  if (path === '') return { files, sizes, cut }
+  const within = [...files.keys()].filter(at => files[at]!.startsWith(`${path}/`))
+  return { files: within.map(at => files[at]!), sizes: within.map(at => sizes[at]!), cut }
+}
+
+// The commits a request names (`shas`), each once, as many as
+// CHANGES_ASKED; null for none, or for one that isn't a commit id.
+export function changesAsked(shas: string | null): string[] | null {
+  if (!shas) return null
+  const asked = [...new Set(shas.split(','))]
+  return asked.length <= CHANGES_ASKED && asked.every(sha => SHA.test(sha)) ? asked : null
+}