@preventive/upstream 1.0.0-alpha.1 → 1.0.0-alpha.3

package/github.d.ts

@@ -1,16 +1,17 @@
 // 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
+// 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.
+// full commit shas and tree ids, 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 tarballs', so an answer is about the
+// repo asked for. A response is read up to a size limit (64 MiB of JSON,
+// 128 MiB of a file, 512 MiB of a tarball) and within a timeout (30
+// seconds, 5 minutes for a tarball), and what it says goes into an error
+// message escaped.
 
 // `owner/name`.
 export type RepoName = string
@@ -24,6 +25,16 @@ export interface ClientOptions {
 
 export type PullRequestStatus = 'open' | 'draft' | 'closed' | 'merged'
 
+// An entry of a directory, as git has it, `path` its name: a file
+// (`100644`, `100755` executable) or a symlink (`120000`) is a blob, a
+// directory (`040000`) a tree, a submodule (`160000`) the commit it is at.
+export interface RepoDirEntry {
+  path: string
+  mode: '100644' | '100755' | '120000' | '040000' | '160000'
+  type: 'blob' | 'tree' | 'commit'
+  sha: string
+}
+
 // A failed request: `status` is the HTTP status GitHub answered with.
 export class HttpError extends Error {
   name: 'HttpError'
@@ -54,12 +65,38 @@ export interface Client {
   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.
+  // The repo's gzipped tarball at the full commit `sha`, whole, in memory:
+  // getRepoTreeTarball's for the tree GitHub names for that commit, asked
+  // on every call, cached or not. So its top directory is named for the
+  // tree, and files marked `export-subst` are as committed, not rewritten.
   getRepoTarball(options: { repo: RepoName; sha: string }): Promise<Uint8Array>
+  // The id of the tree at `path`, a directory, in the full commit `sha`, or
+  // of its root without one: from the tree GitHub names for the commit,
+  // down GitHub's listings a directory at a time, each hashed back to its
+  // id. Refused where `path` is no directory.
+  getRepoTreeId(options: { repo: RepoName; sha: string; path?: string }): Promise<string>
+  // The gzipped tarball of a tree, the repo's own or any subdirectory's, by
+  // its id, whole, in memory: GitHub's, its files under one top directory.
+  // Its files are hashed back into git's tree and the id must be `tree`,
+  // whether downloaded or read from setCacheDir's cache (npm.js), where it
+  // is kept by the id alone, for good; a cached copy that does not match
+  // throws. A tarball shows a submodule as an empty directory, and leaves
+  // out a subtree with no file in it: the submodule's commit and the
+  // subtrees come from GitHub's listings of the trees, asked only then, and
+  // the id must still come out `tree`: the bytes are the tree's own, the
+  // same for every repo. So GitHub's tarball is refused for a tree with
+  // files marked `export-ignore`, which it leaves out, and from a repo set
+  // to include Git LFS objects in archives, which replace the pointers git
+  // has; that repo still gets a tree already cached, pointers and all.
+  getRepoTreeTarball(options: { repo: RepoName; tree: 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[]>
+  // The entries of the directory at `path` in the full commit `sha`, or of
+  // its root, found as getRepoTreeId finds it: GitHub's listing, hashed
+  // back to the tree's id, so none is left out or changed.
+  listRepoDir(options: { repo: RepoName; sha: string; path?: string }): Promise<RepoDirEntry[]>
   // 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[]>

package/npm.d.ts

@@ -13,9 +13,9 @@
 // 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) and zips
-// (soldeer.js) don't rely on this, since they are checked against their
-// integrity on every call.
+// 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): void
 
 // A failed request: `status` is the HTTP status the registry answered

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@preventive/upstream",
-  "version": "1.0.0-alpha.1",
+  "version": "1.0.0-alpha.3",
   "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": {
@@ -81,6 +81,7 @@
     "src/pool.js",
     "src/remote.js",
     "src/semver.js",
+    "src/tree.js",
     "src/soldeer.js"
   ],
   "engines": {

package/semver.d.ts

@@ -4,7 +4,7 @@
 // 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
+export function compareVersions(a: string, b: string, options?: { loose?: boolean }): -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.
@@ -13,3 +13,8 @@ export function isExactVersion(version: unknown): version is string
 export function validRange(range: unknown, options?: { loose?: boolean; includePrerelease?: boolean }): string | null
 // Whether some version is in both ranges; throws for one that is not a range.
 export function intersects(a: string, b: string, options?: { loose?: boolean; includePrerelease?: boolean }): boolean
+// The version as semver cleans it, spaces and a leading `=` or `v` dropped,
+// or null: ` =v1.2.3 ` answers `1.2.3`.
+export function clean(version: string, options?: { loose?: boolean } | boolean): string | null
+// The version's major, as semver reads it; throws for one that is not a version.
+export function major(version: string, options?: { loose?: boolean } | boolean): number

package/semver.js

@@ -1 +1 @@
-export { compareVersions, intersects, isExactVersion, satisfies, valid, validRange } from './src/semver.js'
+export { clean, compareVersions, intersects, isExactVersion, major, satisfies, valid, validRange } from './src/semver.js'

package/src/args.js

@@ -63,6 +63,8 @@ export const assertRepoName = assertion('a repository name', isRepoName)
 export const assertRepo = assertion('"owner/name"', isRepo)
 export const assertRef = assertion('a branch or tag name', isRefName)
 export const assertSha = assertion('a full commit sha', isSha)
+export const isSha1 = matches(/^[\da-f]{40}$/u)
+export const assertTreeId = assertion('a full tree id', isSha1)
 export const assertPath = assertion('a path inside a repository', isRepoPath)
 export const assertToken = assertion('a token', isToken)
 export const assertTokenOrNull = assertion('a token, or null for anonymous access', (value) => value === null || isToken(value))

package/src/cache.js

@@ -6,7 +6,7 @@ import { dirname, join, resolve } from 'node:path'
 import { assertDirectoryPath } 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/zips'])
+const DIRS = new Set(['npm/repos', 'npm/tarballs', 'cargo/repos', 'cargo/crates', 'composer/repos', 'soldeer/zips', 'github/trees'])
 const RECORD_TTL_MS = 30 * 24 * 60 * 60 * 1000 // A link only moves on a transfer or rename, and GitHub redirects those.
 
 let root

package/src/download.js

@@ -3,12 +3,15 @@ import { createHash } from 'node:crypto'
 
 import { readCache, readRegularFile, writeCache } from './cache.js'
 import { request } from './http.js'
+import { gitTreeOfTarball } from './tree.js'
 
 // A hash as each registry writes it: npm's integrity, one sha512 in base64
-// after `sha512-`; crates.io's and Soldeer's checksum, a sha256 in hex.
+// after `sha512-`; crates.io's and Soldeer's checksum, a sha256 in hex; a
+// git tree id for a tarball of that tree.
 const DIGESTS = {
   sha512: (bytes) => `sha512-${createHash('sha512').update(bytes).digest('base64')}`,
   sha256: (bytes) => createHash('sha256').update(bytes).digest('hex'),
+  tree: gitTreeOfTarball,
 }
 
 // Bytes whose `algorithm` hash is `expected`, which the registry or the
@@ -16,23 +19,23 @@ const DIGESTS = {
 // other tools' caches (read, never written; a mismatch is passed over),
 // else ours (a mismatch throws), else what `locate` answers, checked and
 // then cached.
-export async function verifiedDownload({ method, dir, what, ext, algorithm, expected, local = [], locate }) {
+export async function verifiedDownload({ method, dir, what, ext, algorithm, expected, local = [], locate, options = {}, list }) {
   assert.ok(Object.hasOwn(DIGESTS, algorithm) && typeof expected === 'string' && expected !== '', `${method}: nothing to check ${what} against`)
-  const digest = DIGESTS[algorithm]
+  const digest = (bytes) => DIGESTS[algorithm](bytes, { expected, list })
   for (const path of local) {
     const bytes = await readRegularFile(path)
-    if (bytes && digest(bytes) === expected) return bytes
+    if (bytes && await digest(bytes) === expected) return bytes
   }
-  const check = (bytes, from) => {
-    const actual = digest(bytes)
+  const check = async (bytes, from) => {
+    const actual = await digest(bytes)
     assert.ok(actual === expected, `${method}: integrity mismatch for ${what} from ${from}: expected ${expected}, got ${actual}`)
     return bytes
   }
   const key = `${what}.${ext}`
   const cached = await readCache(dir, key)
-  if (cached) return check(cached, 'the cache')
+  if (cached) return await check(cached, 'the cache')
   const url = await locate()
-  const bytes = check(await request(url, { as: 'bytes' }), url)
+  const bytes = await check(await request(url, { ...options, as: 'bytes' }), url)
   await writeCache(dir, key, bytes)
   return bytes
 }

package/src/github/read.js

@@ -2,8 +2,10 @@ import assert from 'node:assert/strict'
 import { Buffer } from 'node:buffer'
 import { createHash } from 'node:crypto'
 
-import { assertArgs, assertGhsa, assertLogin, assertNumber, assertPath, assertRef, assertRepo, assertSha, isSha, optional, sameName, show } from '../args.js'
+import { assertArgs, assertGhsa, assertLogin, assertNumber, assertPath, assertRef, assertRepo, assertSha, assertTreeId, isSha, isSha1, optional, sameName, show } from '../args.js'
+import { verifiedDownload } from '../download.js'
 import { decode, encodeSegment } from '../http.js'
+import { gitTreeOfListing } from '../tree.js'
 import { api, bindMethods, call, clientHeaders, isGone, repoApi } from './client.js'
 
 const PER_PAGE = 100
@@ -66,11 +68,67 @@ async function getRepoFile(headers, options) {
   return decode(bytes, url)
 }
 
-// The one request that follows a redirect, to codeload.github.com. A full
-// sha only, so the bytes are that commit's, not wherever a ref points now.
+// Follows the redirect to codeload.github.com. A tree id names its content,
+// so the bytes are held to it, downloaded or cached, and cached by it alone,
+// for good. What a tarball cannot show, a submodule's commit or a subtree
+// with nothing in it, comes from GitHub's listings of the trees, which the
+// id checks as well: a directory at a time, as a recursive listing of a
+// large tree is cut short.
+async function treeTarball(method, headers, repo, tree) {
+  const listings = new Map()
+  const list = (sha) => {
+    if (!listings.has(sha)) listings.set(sha, call(headers, repoApi(repo, ['git', 'trees', sha])).then((listing) => (Array.isArray(listing?.tree) ? listing.tree : [])))
+    return listings.get(sha)
+  }
+  const locate = () => repoApi(repo, ['tarball', tree])
+  return await verifiedDownload({ method, dir: 'github/trees', what: tree, ext: 'tgz', algorithm: 'tree', expected: tree, locate, options: { headers, redirect: 'follow' }, list })
+}
+
+async function commitTree(method, headers, repo, sha) {
+  const commit = await call(headers, repoApi(repo, ['git', 'commits', sha]))
+  assert.ok(commit?.sha === sha && isSha1(commit.tree?.sha), `${method}: GitHub names no tree for ${repo}@${sha}`)
+  return commit.tree.sha
+}
+
+// A full sha only, so the bytes are that commit's, not wherever a ref points
+// now. Its tree's tarball, not its own, in which `git archive` rewrites the
+// files marked `export-subst`.
 async function getRepoTarball(headers, options) {
   assertArgs('getRepoTarball', options, { repo: assertRepo, sha: assertSha })
-  return await call(headers, repoApi(options.repo, ['tarball', options.sha]), { as: 'bytes', redirect: 'follow' })
+  const { repo, sha } = options
+  const tree = await commitTree('getRepoTarball', headers, repo, sha)
+  return await treeTarball('getRepoTarball', headers, repo, tree)
+}
+
+async function getRepoTreeTarball(headers, options) {
+  assertArgs('getRepoTreeTarball', options, { repo: assertRepo, tree: assertTreeId })
+  return await treeTarball('getRepoTreeTarball', headers, options.repo, options.tree)
+}
+
+// Not recursive: GitHub cuts short a recursive listing of a large tree.
+async function listTree(method, headers, repo, tree) {
+  const entries = (await call(headers, repoApi(repo, ['git', 'trees', tree])))?.tree
+  assert.ok(Array.isArray(entries) && gitTreeOfListing(entries) === tree, `${method}: GitHub's listing of tree ${tree} in ${repo} is not that tree`)
+  return entries.map(({ path, mode, type, sha }) => ({ path, mode, type, sha }))
+}
+
+async function treeAt(method, headers, options) {
+  assertArgs(method, options, { repo: assertRepo, sha: assertSha, path: optional(assertPath) })
+  const { repo, sha, path } = options
+  let tree = await commitTree(method, headers, repo, sha)
+  for (const name of path?.split('/') ?? []) {
+    const entry = (await listTree(method, headers, repo, tree)).find((candidate) => candidate.path === name)
+    assert.ok(entry?.type === 'tree', `${method}: ${repo}@${sha} has no directory at ${show(path)}`)
+    tree = entry.sha
+  }
+  return tree
+}
+
+const getRepoTreeId = (headers, options) => treeAt('getRepoTreeId', headers, options)
+
+async function listRepoDir(headers, options) {
+  const tree = await treeAt('listRepoDir', headers, options)
+  return await listTree('listRepoDir', headers, options.repo, tree)
 }
 
 async function getPullRequest(headers, options) {
@@ -120,5 +178,5 @@ async function listRepoAdvisories(headers, options) {
   return list
 }
 
-export const readMethods = { getCurrentUser, listUserRepos, getRepo, getRepoHead, getRepoFile, getRepoTarball, getPullRequest, getCollaboratorPermission, getAdvisory, listRepoAdvisories }
+export const readMethods = { getCurrentUser, listUserRepos, getRepo, getRepoHead, getRepoFile, getRepoTarball, getRepoTreeTarball, getRepoTreeId, listRepoDir, getPullRequest, getCollaboratorPermission, getAdvisory, listRepoAdvisories }
 export const createClient = (options) => bindMethods(clientHeaders('createClient', options, true), readMethods)

package/src/semver.js

@@ -40,3 +40,5 @@ export const intersects = (...args) => semver().intersects(...args)
 export const compareVersions = (...args) => semver().compare(...args)
 export const valid = (version, ...rest) => (rest.length === 0 && typeof version === 'string' && PLAIN_RELEASE.test(version) ? version : semver().valid(version, ...rest))
 export const isExactVersion = (version) => typeof version === 'string' && valid(version) === version
+export const clean = (...args) => semver().clean(...args)
+export const major = (...args) => semver().major(...args)

package/src/tree.js

@@ -0,0 +1,194 @@
+import { Buffer } from 'node:buffer'
+import { createHash } from 'node:crypto'
+import { gunzipSync } from 'node:zlib'
+
+import { isSha1, matches } from './args.js'
+
+const BLOCK = 512
+const MAX_UNPACKED_BYTES = 2 ** 30
+// Only what git writes is read: anything else, a pax `size` or a mode of
+// 0000, would be extracted as it is not hashed. Modes are as its umask,
+// 002 or 022, leaves them: a file 0664 or 0644, 0775 or 0755 executable;
+// a directory 0775 or 0755; a symlink 0777.
+const PAX_KEYS = new Set(['path', 'linkpath'])
+const MODES = { 0: [0o664, 0o644, 0o775, 0o755], 2: [0o777], 5: [0o775, 0o755] }
+// The top directory is not hashed, so it is held to GitHub's name for it,
+// owner-repo-id: another, `..\..`, `C:` or a Windows device such as
+// `con.txt`, could take an extractor elsewhere.
+const isTop = matches(/^(?!(?:con|prn|aux|nul|com\d|lpt\d)(?:\.|$))[\da-z][\w.-]*$/iu)
+
+// Names are kept as latin1 strings, a char per byte, so they sort and hash
+// as the bytes git has.
+const field = (header, start, end) => {
+  const bytes = header.subarray(start, end)
+  const nul = bytes.indexOf(0)
+  return Buffer.from(nul === -1 ? bytes : bytes.subarray(0, nul)).toString('latin1')
+}
+const octal = (header, start, end) => {
+  const text = field(header, start, end).trim()
+  return /^[0-7]{1,12}$/u.test(text) ? Number.parseInt(text, 8) : Number.NaN
+}
+const objectId = (type, content) => createHash('sha1').update(`${type} ${content.length}\0`).update(content).digest()
+const checksum = (header) => header.reduce((sum, byte, i) => sum + (i >= 148 && i < 156 ? 32 : byte), 0)
+const isZero = (bytes) => bytes.every((byte) => byte === 0)
+
+// `<length> <key>=<value>\n`, the length counting the whole record. A NUL
+// would end a path for an extractor, and a name in a tree for git.
+function paxRecords(body) {
+  const text = Buffer.from(body).toString('latin1')
+  const records = new Map()
+  for (let at = 0; at < text.length;) {
+    const space = text.indexOf(' ', at)
+    const length = text.slice(at, space)
+    const end = at + Number(length)
+    if (!/^[1-9]\d*$/u.test(length) || end > text.length || text[end - 1] !== '\n') return null
+    const record = text.slice(space + 1, end - 1)
+    const equals = record.indexOf('=')
+    if (equals < 1 || record.includes('\0')) return null
+    records.set(record.slice(0, equals), record.slice(equals + 1))
+    at = end
+  }
+  return records
+}
+
+// Git keeps no empty directory: in a tarball, one is a submodule. Each as
+// [the directory holding it, its name, its path].
+function emptyDirs(dir, prefix = '') {
+  return [...dir].flatMap(([name, entry]) => {
+    if (!(entry instanceof Map)) return []
+    const path = `${prefix}${name}`
+    return entry.size === 0 ? [[dir, name, path]] : emptyDirs(entry, `${path}/`)
+  })
+}
+
+// Git sorts a subtree as if its name ended in `/`.
+function treeId(dir) {
+  const entries = [...dir].map(([name, entry]) => (entry instanceof Map ? { mode: '40000', name, id: treeId(entry) } : { ...entry, name }))
+  const key = ({ mode, name }) => (mode === '40000' ? `${name}/` : name)
+  entries.sort((a, b) => (key(a) < key(b) ? -1 : Number(key(a) > key(b))))
+  return objectId('tree', Buffer.concat(entries.flatMap(({ mode, name, id }) => [Buffer.from(`${mode} ${name}\0`, 'latin1'), id])))
+}
+
+const EMPTY_TREE = objectId('tree', Buffer.alloc(0)).toString('hex')
+const isName = matches(/^[^\0/]+$/u)
+const isEntry = (entry) => isName(entry?.path) && isSha1(entry.sha)
+const nameOf = (path) => Buffer.from(path).toString('latin1')
+const subtree = (sha) => ({ mode: '40000', id: Buffer.from(sha, 'hex') })
+
+// A subtree with nothing in it but subtrees like it, down to the empty
+// tree: its listing, read as subtrees alone, hashes to its id.
+async function holdsNothing(sha, listed) {
+  if (sha === EMPTY_TREE) return true
+  const entries = await listed(sha)
+  if (treeId(new Map(entries.map((entry) => [entry.name, subtree(entry.sha)]))).toString('hex') !== sha) return false
+  for (const entry of entries) if (!await holdsNothing(entry.sha, listed)) return false
+  return true
+}
+
+// `git archive` leaves out a subtree with no file in it, which only
+// plumbing makes. Where a directory's id is not the one listed, its listing
+// names any, and one is put back only once its own listings show it holds
+// nothing.
+async function putBackEmptyTrees(dir, sha, listed) {
+  if (treeId(dir).toString('hex') === sha) return
+  for (const entry of await listed(sha)) {
+    if (entry.type !== 'tree') continue
+    const here = dir.get(entry.name)
+    if (here instanceof Map) await putBackEmptyTrees(here, entry.sha, listed)
+    else if (here === undefined && await holdsNothing(entry.sha, listed)) dir.set(entry.name, subtree(entry.sha))
+  }
+}
+
+// The id of the git tree a gzipped tarball holds, as `git archive` writes
+// one, under a single top directory: a file's mode is its exec bit, a
+// symlink's blob its target. What a tarball cannot show comes from `list`,
+// which answers a listing of a tree by its id, as GitHub's trees API does
+// ({ type, path, sha } entries), walked from `expected`: a submodule's
+// commit for an empty directory, and, where the id comes out otherwise, the
+// subtrees with nothing in them it leaves out. The id is `expected` only if
+// those are right. Where there is no such tree, a reason, never an id.
+export async function gitTreeOfTarball(gzipped, { expected, list } = {}) {
+  let bytes
+  try {
+    bytes = gunzipSync(gzipped, { maxOutputLength: MAX_UNPACKED_BYTES })
+  } catch {
+    return 'no tree: not gzip, or larger than 1 GiB unpacked'
+  }
+  const root = new Map()
+  let top
+  let pax = null
+  for (let at = 0; ;) {
+    const header = bytes.subarray(at, at + BLOCK)
+    if (header.length < BLOCK) return 'no tree: the tarball is cut short'
+    if (isZero(header)) {
+      if (!isZero(bytes.subarray(at))) return 'no tree: data after the end of the tarball'
+      break
+    }
+    if (Buffer.from(header.subarray(257, 265)).toString('latin1') !== 'ustar\u000000') return 'no tree: a header that is not POSIX ustar'
+    if (octal(header, 148, 156) !== checksum(header)) return 'no tree: a header that fails its checksum'
+    const size = octal(header, 124, 136)
+    const body = bytes.subarray(at + BLOCK, at + BLOCK + size)
+    if (body.length !== size) return 'no tree: the tarball is cut short'
+    at += BLOCK + Math.ceil(size / BLOCK) * BLOCK
+    const type = String.fromCodePoint(header[156])
+    if (type === 'x') {
+      const records = paxRecords(body)
+      if (records === null) return 'no tree: a malformed pax header'
+      const other = [...records.keys()].find((key) => !PAX_KEYS.has(key))
+      if (other !== undefined) return `no tree: a pax record git does not write, ${JSON.stringify(other)}`
+      if (pax !== null) return 'no tree: two pax headers for one entry'
+      pax = records
+      continue
+    }
+    const prefix = field(header, 345, 500)
+    const path = pax?.get('path') ?? (prefix ? `${prefix}/${field(header, 0, 100)}` : field(header, 0, 100))
+    const target = pax?.get('linkpath') ?? field(header, 157, 257)
+    pax = null
+    if (!Object.hasOwn(MODES, type)) return `no tree: an entry of type ${JSON.stringify(type)}`
+    const mode = octal(header, 100, 108)
+    const asGitWrites = MODES[type].includes(mode) && (type === '0' || size === 0) && path.endsWith('/') === (type === '5')
+      && octal(header, 108, 116) === 0 && octal(header, 116, 124) === 0 && field(header, 265, 297) === 'root' && field(header, 297, 329) === 'root'
+    if (!asGitWrites) return `no tree: a header git does not write, ${JSON.stringify(path)}`
+    const [first, ...parts] = path.replace(/\/$/u, '').split('/')
+    top ??= first
+    const name = type === '5' ? null : parts.pop()
+    if (!isTop(first) || first !== top || name === undefined || [...parts, name].some((part) => ['', '.', '..'].includes(part))) return `no tree: an entry outside one top directory, ${JSON.stringify(path)}`
+    let dir = root
+    for (const part of parts) {
+      if (!dir.has(part)) dir.set(part, new Map())
+      dir = dir.get(part)
+      if (!(dir instanceof Map)) return `no tree: a file where a directory is, ${JSON.stringify(path)}`
+    }
+    if (name === null) continue
+    if (dir.has(name)) return `no tree: ${JSON.stringify(path)} twice`
+    dir.set(name, type === '0' ? { mode: mode & 0o100 ? '100755' : '100644', id: objectId('blob', body) } : { mode: '120000', id: objectId('blob', Buffer.from(target, 'latin1')) })
+  }
+  if (top === undefined) return 'no tree: an empty tarball'
+  const listed = async (sha) => (list && isSha1(sha) ? await list(sha) : [])
+    .filter(isEntry)
+    .map((entry) => ({ ...entry, name: nameOf(entry.path) }))
+  for (const [dir, name, path] of emptyDirs(root)) {
+    let sha = expected
+    const parts = path.split('/')
+    for (const [i, part] of parts.entries()) {
+      const type = i === parts.length - 1 ? 'commit' : 'tree'
+      sha = (await listed(sha)).find((entry) => entry.type === type && entry.name === part)?.sha
+    }
+    if (!isSha1(sha)) return `no tree: an empty directory, ${JSON.stringify(path)}, and no submodule there`
+    dir.set(name, { mode: '160000', id: Buffer.from(sha, 'hex') })
+  }
+  await putBackEmptyTrees(root, expected, listed)
+  return treeId(root).toString('hex')
+}
+
+// GitHub lists a subtree's mode as `040000`, which git writes `40000`.
+const LISTED = new Set(['100644 blob', '100755 blob', '120000 blob', '040000 tree', '160000 commit'])
+
+// The id of the tree a listing such as GitHub's names, its entries
+// { path, mode, type, sha }, or null where one is not an entry a tree can
+// hold, or a name is there twice.
+export function gitTreeOfListing(entries) {
+  if (!entries.every((entry) => isEntry(entry) && LISTED.has(`${entry.mode} ${entry.type}`))) return null
+  const dir = new Map(entries.map(({ path, mode, sha }) => [nameOf(path), { mode: mode.replace(/^0/u, ''), id: Buffer.from(sha, 'hex') }]))
+  return dir.size === entries.length ? treeId(dir).toString('hex') : null
+}