@fabrika/github-app 0.8.1 → 0.9.0-dev.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@fabrika/github-app",
3
- "version": "0.8.1",
3
+ "version": "0.9.0-dev.1",
4
4
  "type": "module",
5
5
  "repository": {
6
6
  "type": "git",
package/src/errors.ts CHANGED
@@ -2,8 +2,16 @@ export function configurationError(): Error {
2
2
  return new Error('GitHub App configuration is invalid')
3
3
  }
4
4
 
5
- export function requestStatusError(status: number): Error {
6
- return new Error(`GitHub App request failed with status ${status}`)
5
+ /** GitHub answered a request with an unexpected status; the message never carries GitHub's response text. */
6
+ export class GitHubRequestError extends Error {
7
+ constructor(readonly status: number) {
8
+ super(`GitHub App request failed with status ${status}`)
9
+ this.name = 'GitHubRequestError'
10
+ }
11
+ }
12
+
13
+ export function requestStatusError(status: number): GitHubRequestError {
14
+ return new GitHubRequestError(status)
7
15
  }
8
16
 
9
17
  export function responseError(): Error {
package/src/index.ts CHANGED
@@ -1,9 +1,14 @@
1
1
  export { GitHubAppClient } from './client'
2
- export { GitHubBranchConflictError, GitHubNotFoundError, GitHubStaleHeadError } from './errors'
2
+ export { GitHubBranchConflictError, GitHubNotFoundError, GitHubRequestError, GitHubStaleHeadError } from './errors'
3
3
  export { buildGitHubAppManifest, exchangeGitHubAppManifestCode } from './manifest'
4
4
  export type {
5
+ GitHubBlobRead,
6
+ GitHubBlobRef,
7
+ GitHubChangedFile,
8
+ GitHubChangedFileStatus,
5
9
  GitHubCommit,
6
10
  GitHubCommitFilesInput,
11
+ GitHubComparison,
7
12
  GitHubCreateBranchInput,
8
13
  GitHubFileChange,
9
14
  GitHubFileRead,
@@ -15,6 +20,8 @@ export type {
15
20
  GitHubTextFile,
16
21
  GitHubTreeEntry,
17
22
  GitHubTreeListing,
23
+ GitHubUnreadablePath,
24
+ GitHubUnreadableReason,
18
25
  } from './repository-types'
19
26
  export { pemToPkcs8 } from './signing'
20
27
  export type {
@@ -32,11 +32,59 @@ export interface GitHubTextFile {
32
32
  readonly content: string
33
33
  }
34
34
 
35
+ /**
36
+ * Why a requested path was not read: `missing` (no such path), `not_a_file` (a directory, symlink or submodule),
37
+ * `too_large` (over the per-file bound), `binary` (not UTF-8), `budget` (past the read's total byte bound).
38
+ */
39
+ export type GitHubUnreadableReason = 'missing' | 'not_a_file' | 'too_large' | 'binary' | 'budget'
40
+
41
+ export interface GitHubUnreadablePath {
42
+ readonly path: string
43
+ readonly reason: GitHubUnreadableReason
44
+ }
45
+
35
46
  export interface GitHubFileRead {
36
47
  readonly commitSha: string
37
48
  readonly files: readonly GitHubTextFile[]
38
- /** Requested paths that do not exist (or are not regular UTF-8 files) at `commitSha`. */
39
- readonly missingPaths: readonly string[]
49
+ /** Requested paths that were not read at `commitSha`, in request order. */
50
+ readonly unreadable: readonly GitHubUnreadablePath[]
51
+ }
52
+
53
+ /** A blob named by a tree listing of the same repository. */
54
+ export interface GitHubBlobRef {
55
+ readonly path: string
56
+ readonly sha: string
57
+ readonly size: number
58
+ }
59
+
60
+ export interface GitHubBlobRead {
61
+ readonly files: readonly GitHubTextFile[]
62
+ /** Blobs that were not read (`too_large`, `budget` or `binary`), in request order. */
63
+ readonly unreadable: readonly GitHubUnreadablePath[]
64
+ }
65
+
66
+ export type GitHubChangedFileStatus = 'added' | 'removed' | 'modified' | 'renamed' | 'copied' | 'changed' | 'unchanged'
67
+
68
+ export interface GitHubChangedFile {
69
+ readonly path: string
70
+ /** The path before a rename or copy. */
71
+ readonly previousPath: string | null
72
+ readonly status: GitHubChangedFileStatus
73
+ readonly additions: number
74
+ readonly deletions: number
75
+ /** The unified diff hunk; null when GitHub omits it (a binary file or a very large change). */
76
+ readonly patch: string | null
77
+ }
78
+
79
+ export interface GitHubComparison {
80
+ readonly baseSha: string
81
+ readonly headSha: string
82
+ /** Commits on head that are not on base. */
83
+ readonly aheadBy: number
84
+ readonly behindBy: number
85
+ readonly files: readonly GitHubChangedFile[]
86
+ /** GitHub lists at most 300 files of a comparison; true when it listed that many, so more may have changed. */
87
+ readonly filesCapped: boolean
40
88
  }
41
89
 
42
90
  export interface GitHubFileChange {
@@ -84,8 +132,14 @@ export interface GitHubRepositoryClient {
84
132
  readRef(branch: string, signal?: AbortSignal): Promise<GitHubRef | null>
85
133
  readTree(commitSha: string, directory?: string, signal?: AbortSignal): Promise<GitHubTreeListing>
86
134
  readFiles(commitSha: string, paths: readonly string[], signal?: AbortSignal): Promise<GitHubFileRead>
135
+ /** Reads listed blobs as text without walking the tree again, within the same per-file and total bounds as `readFiles`. */
136
+ readBlobTexts(blobs: readonly GitHubBlobRef[], signal?: AbortSignal): Promise<GitHubBlobRead>
137
+ /** The changes from the merge base of `baseSha` and `headSha` to `headSha`. */
138
+ compareCommits(baseSha: string, headSha: string, signal?: AbortSignal): Promise<GitHubComparison>
87
139
  /** Idempotent: an existing branch already at `fromSha` is returned; one elsewhere is a conflict. */
88
140
  createBranch(input: GitHubCreateBranchInput): Promise<GitHubRef>
141
+ /** Idempotent: `deleted` is false when the branch did not exist. GitHub closes an open pull request from it. */
142
+ deleteBranch(branch: string, signal?: AbortSignal): Promise<{ readonly deleted: boolean }>
89
143
  /** Creates exactly one commit on top of `expectedHeadSha` and moves the branch to it without force. */
90
144
  commitFiles(input: GitHubCommitFilesInput): Promise<GitHubCommit>
91
145
  openPullRequest(input: GitHubOpenPullRequestInput): Promise<GitHubPullRequestRef>
@@ -1,6 +1,6 @@
1
1
  import { z } from 'zod'
2
2
  import { configurationError, responseError } from './errors'
3
- import type { GitHubCommit, GitHubPullRequestRef, GitHubRef, GitHubTreeEntry } from './repository-types'
3
+ import type { GitHubCommit, GitHubComparison, GitHubPullRequestRef, GitHubRef, GitHubTreeEntry } from './repository-types'
4
4
  import { hasAsciiControl } from './validation'
5
5
 
6
6
  export const MAX_TREE_ENTRIES = 5000
@@ -20,6 +20,10 @@ export const MAX_PULL_REQUEST_RESPONSE_BYTES = 1024 * 1024
20
20
  // A commit echoes its message, which existing history does not bound.
21
21
  export const MAX_COMMIT_RESPONSE_BYTES = 1024 * 1024
22
22
  export const MAX_PATH_SEGMENTS = 64
23
+ /** GitHub's own bound on the files of one comparison. */
24
+ export const MAX_COMPARE_FILES = 300
25
+ // Each file of a comparison carries its patch.
26
+ export const MAX_COMPARE_RESPONSE_BYTES = 8 * 1024 * 1024
23
27
 
24
28
  const SHA_PATTERN = /^[a-f0-9]{40}$/
25
29
  const LONE_SURROGATE_PATTERN = /[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/
@@ -137,6 +141,41 @@ export function decodeTextBlob(body: unknown, expectedSha: string, expectedSize:
137
141
  }
138
142
  }
139
143
 
144
+ const comparisonSchema = z.object({
145
+ ahead_by: z.number().int().nonnegative(),
146
+ behind_by: z.number().int().nonnegative(),
147
+ merge_base_commit: z.object({ sha: shaSchema }),
148
+ files: z.array(z.object({
149
+ filename: z.string(),
150
+ previous_filename: z.string().optional(),
151
+ status: z.enum(['added', 'removed', 'modified', 'renamed', 'copied', 'changed', 'unchanged']),
152
+ additions: z.number().int().nonnegative(),
153
+ deletions: z.number().int().nonnegative(),
154
+ patch: z.string().optional(),
155
+ })).max(MAX_COMPARE_FILES).optional(),
156
+ })
157
+
158
+ export function decodeComparison(body: unknown, headSha: string): GitHubComparison {
159
+ const result = comparisonSchema.safeParse(body)
160
+ if (!result.success) throw responseError()
161
+ const files = (result.data.files ?? []).map((file) => ({
162
+ path: file.filename,
163
+ previousPath: file.previous_filename ?? null,
164
+ status: file.status,
165
+ additions: file.additions,
166
+ deletions: file.deletions,
167
+ patch: file.patch ?? null,
168
+ }))
169
+ return {
170
+ baseSha: result.data.merge_base_commit.sha,
171
+ headSha,
172
+ aheadBy: result.data.ahead_by,
173
+ behindBy: result.data.behind_by,
174
+ files,
175
+ filesCapped: files.length === MAX_COMPARE_FILES,
176
+ }
177
+ }
178
+
140
179
  const pullRequestSchema = z.object({ number: z.number().int().positive(), html_url: z.string().url() })
141
180
 
142
181
  export function decodePullRequest(body: unknown, created: boolean): GitHubPullRequestRef {
package/src/repository.ts CHANGED
@@ -1,7 +1,10 @@
1
1
  import { configurationError, GitHubBranchConflictError, GitHubNotFoundError, GitHubStaleHeadError, requestStatusError, responseError } from './errors'
2
2
  import type {
3
+ GitHubBlobRead,
4
+ GitHubBlobRef,
3
5
  GitHubCommit,
4
6
  GitHubCommitFilesInput,
7
+ GitHubComparison,
5
8
  GitHubCreateBranchInput,
6
9
  GitHubFileRead,
7
10
  GitHubOpenPullRequestInput,
@@ -11,9 +14,12 @@ import type {
11
14
  GitHubTextFile,
12
15
  GitHubTreeEntry,
13
16
  GitHubTreeListing,
17
+ GitHubUnreadablePath,
18
+ GitHubUnreadableReason,
14
19
  } from './repository-types'
15
20
  import {
16
21
  decodeCommit,
22
+ decodeComparison,
17
23
  decodeCreatedTreeSha,
18
24
  decodePullRequest,
19
25
  decodePullRequestList,
@@ -26,6 +32,7 @@ import {
26
32
  MAX_CHANGED_FILES,
27
33
  MAX_COMMIT_MESSAGE_BYTES,
28
34
  MAX_COMMIT_RESPONSE_BYTES,
35
+ MAX_COMPARE_RESPONSE_BYTES,
29
36
  MAX_FILE_BYTES,
30
37
  MAX_PULL_REQUEST_BODY_BYTES,
31
38
  MAX_PULL_REQUEST_RESPONSE_BYTES,
@@ -54,10 +61,13 @@ export interface RepositoryClientConfig {
54
61
  readonly timeoutMs: number
55
62
  }
56
63
 
64
+ /** Blob reads in flight at once; enough to hide latency, few enough to stay clear of GitHub's secondary rate limits. */
65
+ const BLOB_READ_CONCURRENCY = 6
66
+
57
67
  type RequestResult = { readonly ok: true; readonly body: unknown } | { readonly ok: false; readonly status: number }
58
68
 
59
69
  interface RequestOptions {
60
- readonly method?: 'GET' | 'POST' | 'PATCH'
70
+ readonly method?: 'GET' | 'POST' | 'PATCH' | 'DELETE'
61
71
  readonly body?: unknown
62
72
  readonly signal?: AbortSignal | undefined
63
73
  readonly maxResponseBytes?: number
@@ -112,25 +122,74 @@ class RepositoryClient implements GitHubRepositoryClient {
112
122
  for (const path of paths) validatePath(path)
113
123
  const directories = this.#treeWalker((await this.#readCommit(commitSha, signal)).treeSha, signal)
114
124
  const files: GitHubTextFile[] = []
115
- const missingPaths: string[] = []
125
+ const unreadable: GitHubUnreadablePath[] = []
116
126
  let remainingBytes = MAX_READ_BYTES
117
127
  for (const path of paths) {
118
- const entry = await directories.find(path)
119
- // Oversized files, and files past the total read budget, are reported missing like other unreadable paths.
120
- if (entry?.type !== 'blob' || entry.mode === '120000' || entry.size > MAX_FILE_BYTES || entry.size > remainingBytes) {
121
- missingPaths.push(path)
128
+ const entry = readableBlob(await directories.find(path), remainingBytes)
129
+ if (typeof entry === 'string') {
130
+ unreadable.push({ path, reason: entry })
122
131
  continue
123
132
  }
124
133
  const body = await this.#readGitObject(`/git/blobs/${entry.sha}`, signal, MAX_BLOB_RESPONSE_BYTES)
125
134
  const content = decodeTextBlob(body, entry.sha, entry.size)
126
135
  if (content === null) {
127
- missingPaths.push(path)
136
+ unreadable.push({ path, reason: 'binary' })
128
137
  continue
129
138
  }
130
139
  remainingBytes -= entry.size
131
140
  files.push({ path, content })
132
141
  }
133
- return { commitSha, files, missingPaths }
142
+ return { commitSha, files, unreadable }
143
+ }
144
+
145
+ async readBlobTexts(blobs: readonly GitHubBlobRef[], signal?: AbortSignal): Promise<GitHubBlobRead> {
146
+ if (blobs.length === 0 || blobs.length > MAX_READ_PATHS || new Set(blobs.map((blob) => blob.path)).size !== blobs.length) {
147
+ throw configurationError()
148
+ }
149
+ for (const blob of blobs) {
150
+ validatePath(blob.path)
151
+ validateSha(blob.sha)
152
+ if (!Number.isSafeInteger(blob.size) || blob.size < 0) throw configurationError()
153
+ }
154
+ const unreadable = new Map<string, GitHubUnreadableReason>()
155
+ const selected: GitHubBlobRef[] = []
156
+ let remainingBytes = MAX_READ_BYTES
157
+ for (const blob of blobs) {
158
+ if (blob.size > MAX_FILE_BYTES) unreadable.set(blob.path, 'too_large')
159
+ else if (blob.size > remainingBytes) unreadable.set(blob.path, 'budget')
160
+ else {
161
+ remainingBytes -= blob.size
162
+ selected.push(blob)
163
+ }
164
+ }
165
+ const contents = new Map<string, string>()
166
+ for (let start = 0; start < selected.length; start += BLOB_READ_CONCURRENCY) {
167
+ await Promise.all(
168
+ selected.slice(start, start + BLOB_READ_CONCURRENCY).map(async (blob) => {
169
+ const body = await this.#readGitObject(`/git/blobs/${blob.sha}`, signal, MAX_BLOB_RESPONSE_BYTES)
170
+ const content = decodeTextBlob(body, blob.sha, blob.size)
171
+ if (content === null) unreadable.set(blob.path, 'binary')
172
+ else contents.set(blob.path, content)
173
+ }),
174
+ )
175
+ }
176
+ const files: GitHubTextFile[] = []
177
+ const unread: GitHubUnreadablePath[] = []
178
+ for (const blob of blobs) {
179
+ const content = contents.get(blob.path)
180
+ const reason = unreadable.get(blob.path)
181
+ if (content !== undefined) files.push({ path: blob.path, content })
182
+ else if (reason !== undefined) unread.push({ path: blob.path, reason })
183
+ }
184
+ return { files, unreadable: unread }
185
+ }
186
+
187
+ async compareCommits(baseSha: string, headSha: string, signal?: AbortSignal): Promise<GitHubComparison> {
188
+ validateSha(baseSha)
189
+ validateSha(headSha)
190
+ // The changed files ride only on the first page of commits, so one commit per page keeps the rest of the body small.
191
+ const body = await this.#readGitObject(`/compare/${baseSha}...${headSha}?per_page=1`, signal, MAX_COMPARE_RESPONSE_BYTES)
192
+ return decodeComparison(body, headSha)
134
193
  }
135
194
 
136
195
  async createBranch(input: GitHubCreateBranchInput): Promise<GitHubRef> {
@@ -152,6 +211,15 @@ class RepositoryClient implements GitHubRepositoryClient {
152
211
  return requireBranchAt(raced, input.fromSha)
153
212
  }
154
213
 
214
+ async deleteBranch(branch: string, signal?: AbortSignal): Promise<{ readonly deleted: boolean }> {
215
+ validateBranch(branch)
216
+ const result = await this.#request(`/git/refs/heads/${encodeBranch(branch)}`, { method: 'DELETE', signal, expectedFailures: [422] })
217
+ if (result.ok) return { deleted: true }
218
+ // 422 is "Reference does not exist" among other refusals; only an absent branch counts as already deleted.
219
+ if (await this.readRef(branch, signal) !== null) throw requestStatusError(result.status)
220
+ return { deleted: false }
221
+ }
222
+
155
223
  async commitFiles(input: GitHubCommitFilesInput): Promise<GitHubCommit> {
156
224
  validateBranch(input.branch)
157
225
  validateSha(input.expectedHeadSha)
@@ -288,6 +356,7 @@ class RepositoryClient implements GitHubRepositoryClient {
288
356
  if (options.expectedFailures?.includes(response.status) === true) return { ok: false, status: response.status }
289
357
  throw requestStatusError(response.status)
290
358
  }
359
+ if (response.status === 204) return { ok: true, body: null }
291
360
  return { ok: true, body: await readBoundedJson(response, cancellation, options.maxResponseBytes) }
292
361
  } finally {
293
362
  cancellation.dispose()
@@ -334,6 +403,17 @@ class TreeWalker {
334
403
  }
335
404
  }
336
405
 
406
+ type GitHubBlobEntry = Extract<GitHubTreeEntry, { readonly type: 'blob' }>
407
+
408
+ /** The entry when it is a regular file within both bounds, otherwise why it is not read. */
409
+ function readableBlob(entry: GitHubTreeEntry | null, remainingBytes: number): GitHubBlobEntry | GitHubUnreadableReason {
410
+ if (entry === null) return 'missing'
411
+ if (entry.type !== 'blob' || entry.mode === '120000') return 'not_a_file'
412
+ if (entry.size > MAX_FILE_BYTES) return 'too_large'
413
+ if (entry.size > remainingBytes) return 'budget'
414
+ return entry
415
+ }
416
+
337
417
  function requireBranchAt(ref: GitHubRef, sha: string): GitHubRef {
338
418
  if (ref.sha !== sha) throw new GitHubBranchConflictError()
339
419
  return ref