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

package/github.d.ts

@@ -25,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'
@@ -60,6 +70,11 @@ export interface Client {
   // 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`,
@@ -78,6 +93,10 @@ export interface Client {
   // 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@preventive/upstream",
-  "version": "1.0.0-alpha.2",
+  "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": {

package/src/github/read.js

@@ -5,6 +5,7 @@ import { createHash } from 'node:crypto'
 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
@@ -83,15 +84,20 @@ async function treeTarball(method, headers, repo, 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 })
   const { repo, sha } = options
-  const commit = await call(headers, repoApi(repo, ['git', 'commits', sha]))
-  assert.ok(commit?.sha === sha && isSha1(commit.tree?.sha), `getRepoTarball: GitHub names no tree for ${repo}@${sha}`)
-  return await treeTarball('getRepoTarball', headers, repo, commit.tree.sha)
+  const tree = await commitTree('getRepoTarball', headers, repo, sha)
+  return await treeTarball('getRepoTarball', headers, repo, tree)
 }
 
 async function getRepoTreeTarball(headers, options) {
@@ -99,6 +105,32 @@ async function getRepoTreeTarball(headers, options) {
   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) {
   assertArgs('getPullRequest', options, { repo: assertRepo, number: assertNumber })
   const { repo, number } = options
@@ -146,5 +178,5 @@ async function listRepoAdvisories(headers, options) {
   return list
 }
 
-export const readMethods = { getCurrentUser, listUserRepos, getRepo, getRepoHead, getRepoFile, getRepoTarball, getRepoTreeTarball, 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/tree.js

@@ -71,6 +71,8 @@ function treeId(dir) {
 
 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
@@ -163,8 +165,8 @@ export async function gitTreeOfTarball(gzipped, { expected, list } = {}) {
   }
   if (top === undefined) return 'no tree: an empty tarball'
   const listed = async (sha) => (list && isSha1(sha) ? await list(sha) : [])
-    .filter((entry) => isName(entry?.path) && isSha1(entry.sha))
-    .map((entry) => ({ ...entry, name: Buffer.from(entry.path).toString('latin1') }))
+    .filter(isEntry)
+    .map((entry) => ({ ...entry, name: nameOf(entry.path) }))
   for (const [dir, name, path] of emptyDirs(root)) {
     let sha = expected
     const parts = path.split('/')
@@ -178,3 +180,15 @@ export async function gitTreeOfTarball(gzipped, { expected, list } = {}) {
   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
+}