Repository navigation
Expand file tree
/
Copy pathmerge.ts
More file actions
419 lines (399 loc) · 31 KB
/
Copy pathmerge.ts
File metadata and controls
419 lines (399 loc) · 31 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
import { ghEnvironment } from './gh-env.ts';
import { runWithInput } from './run-with-input.ts';
/**
* How long a stopped `gh` gets after SIGTERM before SIGKILL, and how long its inherited output pipes may stay open after
* it exits. Every gh call of this gateway settles only when gh has stopped, so a call aborted at a deadline settles up
* to 0.4 s later. That keeps a merge click (14 s deadline in runner/merge.ts) within 14.4 s, inside the 14.5 s shutdown
* drain and below the 15-second serving request budget, and an inspection (at most 12 s) within 12.4 s.
*/
export const MERGE_KILL_GRACE_MS = 250, MERGE_PIPE_GRACE_MS = 150;
/** The longest deadline of any inspection, and the default for merge-state and queue-state inspections. */
export const MERGE_INSPECTION_TIMEOUT_MS = 12_000;
export interface RequiredCheck {
context: string;
appId: number | null;
state: 'success' | 'pending' | 'failure' | 'missing';
}
export interface RemoteMergeState {
base: string;
head: string;
pullRequestState: 'OPEN' | 'CLOSED' | 'MERGED';
mergeable: 'MERGEABLE' | 'CONFLICTING' | 'UNKNOWN';
rulesKnown: boolean;
atomicBaseGuard: boolean;
mergeQueue: boolean;
requiredChecks: RequiredCheck[];
alreadyFixed: 'clear' | 'found' | 'unknown';
/** The pull request's web URL, when GitHub reports a valid one. Display only; never used to decide readiness. */
url?: string;
}
export interface MergeResult { url: string; }
export class MergeSubmissionError extends Error {
readonly outcome: 'refused' | 'unknown';
constructor(message: string, outcome: 'refused' | 'unknown', options?: ErrorOptions) {
super(message, options);
this.name = 'MergeSubmissionError';
this.outcome = outcome;
}
}
export type MergeQueueEntryPhase = 'AWAITING_CHECKS' | 'LOCKED' | 'MERGEABLE' | 'QUEUED';
export type MergeQueueObservation =
| { state: 'queued'; reviewedHead: string; entryId: string; phase: MergeQueueEntryPhase; position: number; enqueuedAt: string; queueHead: string }
| { state: 'removed'; reviewedHead: string; removedAt: string; reason: string }
| { state: 'failed'; reviewedHead: string; entryId: string; reason: string }
| { state: 'merged'; reviewedHead: string; mergedAt: string };
export interface MergeQueueGateway {
queueWatermark(expectedHead: string, options?: { signal?: AbortSignal; timeoutMs?: number }): Promise<string | null>;
inspectQueue(expectedHead: string, options?: { signal?: AbortSignal; timeoutMs?: number; afterCursor?: string | null }): Promise<MergeQueueObservation>;
}
export interface MergeGateway {
inspect(options?: { fresh?: boolean; timeoutMs?: number; signal?: AbortSignal }): Promise<RemoteMergeState>;
merge(expectedHead: string, options?: { signal?: AbortSignal }): Promise<MergeResult>;
}
export interface GhMergeConfig {
repository: string;
pullRequest: number;
issue: number;
method?: 'merge' | 'squash' | 'rebase';
}
export type RunGh = (args: readonly string[], options?: { signal?: AbortSignal }) => Promise<string>;
function confirmedMergeRefusal(message: string): boolean {
return /required (?:approving )?review|required status check|branch protection|merge conflict|not mergeable|head (?:branch |commit )?(?:was )?(?:modified|changed)|does not match.*head|pull request.*(?:closed|draft)|merge method.*not allowed/i.test(message);
}
function fullSha(value: unknown, label: string): string {
if (typeof value !== 'string' || !/^[a-f0-9]{40}$/.test(value)) throw new Error(`GitHub returned an invalid ${label}.`);
return value;
}
function flattenPages(value: unknown): unknown[] {
if (!Array.isArray(value) || value.some(page => !Array.isArray(page))) throw new Error('GitHub returned an invalid paginated response.');
return value.flat();
}
function timestamp(value: unknown, label: string): string {
if (typeof value !== 'string' || !/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})$/.test(value) || !Number.isFinite(Date.parse(value))) throw new Error(`GitHub returned an invalid ${label}.`);
return value;
}
/** GitHub CLI adapter. All arguments are literal argv; no shell is involved. */
export class GhMergeGateway implements MergeGateway, MergeQueueGateway {
readonly config: GhMergeConfig;
readonly run: RunGh;
#cache: { expiresAt: number; state: RemoteMergeState } | null = null;
#generation = 0;
#inflight: { generation: number; promise: Promise<RemoteMergeState> } | null = null;
constructor(config: GhMergeConfig, run?: RunGh) {
if (!/^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/.test(config.repository) || !Number.isSafeInteger(config.pullRequest) || config.pullRequest < 1 || !Number.isSafeInteger(config.issue) || config.issue < 1)
throw new Error('A GitHub repository, pull request, and issue are required for merging.');
if (config.method !== undefined && !['merge','squash','rebase'].includes(config.method)) throw new Error('GitHub merge method must be merge, squash, or rebase.');
this.config = config;
this.run = run ?? ((args, options) => runWithInput('gh', args, { timeout: 30_000, maxBuffer: 8 * 1024 * 1024, signal: options?.signal, env: ghEnvironment(), killGraceMs: MERGE_KILL_GRACE_MS, pipeGraceMs: MERGE_PIPE_GRACE_MS }));
}
async #json(args: readonly string[], signal?: AbortSignal): Promise<unknown> {
const output = await this.run(args, { signal });
try { return JSON.parse(output); }
catch { throw new Error('GitHub returned invalid JSON.'); }
}
async #optionalJson(args: readonly string[], signal?: AbortSignal): Promise<unknown | null> {
try { return await this.#json(args, signal); }
catch (error) {
if (error instanceof Error && /HTTP 404|not found/i.test(error.message)) return null;
throw error;
}
}
async #alreadyFixed(signal?: AbortSignal): Promise<'clear' | 'found' | 'unknown'> {
try {
const timeline = flattenPages(await this.#json(['api','--paginate','--slurp','-H','Accept: application/vnd.github+json',`repos/${this.config.repository}/issues/${this.config.issue}/timeline`], signal));
const referenced = new Set<number>();
for (const event of timeline) {
if (!event || typeof event !== 'object' || Array.isArray(event)) throw new Error('GitHub returned a malformed timeline event.');
const source = (event as { source?: { issue?: { number?: unknown; pull_request?: unknown; repository_url?: unknown } } }).source?.issue;
if (!source?.pull_request) continue;
if (source.repository_url !== `https://api.github.com/repos/${this.config.repository}`) throw new Error('GitHub returned a cross-repository or incomplete pull request reference.');
if (!Number.isSafeInteger(source.number) || (source.number as number) < 1) throw new Error('GitHub returned an invalid pull request reference.');
if (source.number !== this.config.pullRequest) referenced.add(source.number as number);
}
const numbers = [...referenced];
if (numbers.length > 100) return 'unknown';
if (!numbers.length) return 'clear';
const [owner, name] = this.config.repository.split('/') as [string, string];
const selections = numbers.map((number, index) => `p${index}: pullRequest(number:${number}) { state mergedAt }`).join(' ');
const response = await this.#json(['api','graphql','-f',`query=query { repository(owner:${JSON.stringify(owner)}, name:${JSON.stringify(name)}) { ${selections} } }`], signal) as { data?: { repository?: Record<string, { state?: unknown; mergedAt?: unknown } | null> }; errors?: unknown };
if (Object.hasOwn(response, 'errors') && (!Array.isArray(response.errors) || response.errors.length > 0)) return 'unknown';
const pulls = response.data?.repository;
if (!pulls || Object.keys(pulls).length !== numbers.length) return 'unknown';
for (let index = 0; index < numbers.length; index++) {
const pr = pulls[`p${index}`];
if (!pr) return 'unknown';
if (!['OPEN','CLOSED','MERGED'].includes(String(pr.state)) || !Object.hasOwn(pr, 'mergedAt') || (pr.mergedAt !== null && typeof pr.mergedAt !== 'string')) return 'unknown';
if ((pr.state === 'OPEN' || pr.state === 'CLOSED') && pr.mergedAt !== null) return 'unknown';
if (pr.state === 'MERGED' && typeof pr.mergedAt !== 'string') return 'unknown';
if (pr.state === 'OPEN' || pr.state === 'MERGED') return 'found';
}
return 'clear';
} catch (error) {
if (signal?.aborted) throw error;
return 'unknown';
}
}
async #inspectNow(signal?: AbortSignal): Promise<RemoteMergeState> {
const pr = await this.#json(['pr','view',String(this.config.pullRequest),'--repo',this.config.repository,'--json','baseRefName,baseRefOid,headRefName,headRefOid,state,mergeable,statusCheckRollup,url'], signal) as Record<string, unknown>;
if (typeof pr.baseRefName !== 'string' || typeof pr.headRefName !== 'string' || !['OPEN','CLOSED','MERGED'].includes(String(pr.state)) || !['MERGEABLE','CONFLICTING','UNKNOWN'].includes(String(pr.mergeable)) || !Array.isArray(pr.statusCheckRollup))
throw new Error('GitHub returned an incomplete pull request state.');
const branch = encodeURIComponent(pr.baseRefName);
let rulesKnown = true;
let rules: unknown[] = [];
let classic: unknown | null = null;
try {
rules = flattenPages(await this.#json(['api','--paginate','--slurp',`repos/${this.config.repository}/rules/branches/${branch}`], signal));
const branchState = await this.#json(['api',`repos/${this.config.repository}/branches/${branch}`], signal) as { protected?: unknown };
if (typeof branchState.protected !== 'boolean') throw new Error('GitHub returned an incomplete branch state.');
const protection = await this.#optionalJson(['api',`repos/${this.config.repository}/branches/${branch}/protection`], signal);
if (protection === null) {
if (branchState.protected) throw new Error('Branch protection is present but unreadable.');
} else if (!protection || typeof protection !== 'object' || !('required_status_checks' in protection)) {
throw new Error('GitHub returned incomplete branch protection.');
} else {
const required = (protection as { required_status_checks: unknown }).required_status_checks;
if (required !== null && (typeof required !== 'object' || Array.isArray(required))) throw new Error('GitHub returned malformed branch protection.');
classic = required;
}
} catch { rulesKnown = false; }
const requirements = new Map<string, { context: string; appId: number | null }>();
let atomicBaseGuard = false;
let mergeQueue = false;
if (rulesKnown) {
for (const rule of rules) {
if (!rule || typeof rule !== 'object') { rulesKnown = false; break; }
const value = rule as { type?: unknown; parameters?: Record<string, unknown> };
if (typeof value.type !== 'string') { rulesKnown = false; break; }
if (value.type === 'merge_queue') { mergeQueue = true; atomicBaseGuard = true; }
if (value.type !== 'required_status_checks') continue;
const parameters = value.parameters;
if (!parameters || !Array.isArray(parameters.required_status_checks)) { rulesKnown = false; break; }
if (parameters.strict_required_status_checks_policy === true && parameters.required_status_checks.length > 0) atomicBaseGuard = true;
for (const check of parameters.required_status_checks) {
if (!check || typeof check !== 'object' || typeof (check as { context?: unknown }).context !== 'string') { rulesKnown = false; break; }
const context = (check as { context: string }).context;
if (!Object.hasOwn(check, 'integration_id')) { rulesKnown = false; break; }
const app = (check as { integration_id: unknown }).integration_id;
if (app !== null && (!Number.isSafeInteger(app) || (app as number) < 1)) { rulesKnown = false; break; }
const appId = app as number | null;
requirements.set(`${context}\0${appId ?? ''}`, { context, appId });
}
}
if (classic && typeof classic === 'object') {
const value = classic as { strict?: unknown; checks?: unknown; contexts?: unknown };
const hasChecks = Object.hasOwn(value, 'checks'), hasContexts = Object.hasOwn(value, 'contexts');
if (typeof value.strict !== 'boolean' || (hasChecks && !Array.isArray(value.checks)) || (hasContexts && !Array.isArray(value.contexts)) || (!hasChecks && !hasContexts)) rulesKnown = false;
const contexts = Array.isArray(value.contexts) ? value.contexts : [];
const suppliedChecks = Array.isArray(value.checks) ? value.checks : [];
if (contexts.some(context => typeof context !== 'string') || suppliedChecks.some(check => !check || typeof check !== 'object' || typeof (check as { context?: unknown }).context !== 'string')) rulesKnown = false;
if (rulesKnown && hasChecks && hasContexts) {
const fromContexts = new Set(contexts as string[]), fromChecks = new Set(suppliedChecks.map(check => (check as { context: string }).context));
if (fromContexts.size !== fromChecks.size || [...fromContexts].some(context => !fromChecks.has(context))) rulesKnown = false;
}
const checks = hasChecks ? suppliedChecks : contexts.map(context => ({ context, app_id: null }));
if (rulesKnown && value.strict && checks.length > 0) atomicBaseGuard = true;
if (rulesKnown) for (const check of checks) {
if (!check || typeof check !== 'object' || typeof (check as { context?: unknown }).context !== 'string') { rulesKnown = false; break; }
const context = (check as { context: string }).context;
if (!Object.hasOwn(check, 'app_id')) { rulesKnown = false; break; }
const app = (check as { app_id: unknown }).app_id;
if (app !== null && (!Number.isSafeInteger(app) || (app as number) < 1)) { rulesKnown = false; break; }
const appId = app as number | null;
requirements.set(`${context}\0${appId ?? ''}`, { context, appId });
}
}
}
const observed = pr.statusCheckRollup as Array<Record<string, unknown>>;
const requiredChecks = [...requirements.values()].map(required => {
const match = observed.find(check => {
const context = typeof check.name === 'string' ? check.name : check.context;
const app = check.app && typeof check.app === 'object' ? (check.app as { databaseId?: unknown }).databaseId : null;
return context === required.context && (required.appId === null || app === required.appId);
});
if (!match) return { ...required, state: 'missing' as const };
let state: RequiredCheck['state'];
if (typeof match.name === 'string') {
const status = String(match.status ?? '').toUpperCase();
const conclusion = String(match.conclusion ?? '').toUpperCase();
if (['QUEUED','IN_PROGRESS','WAITING','PENDING','REQUESTED'].includes(status)) state = 'pending';
else if (status === 'COMPLETED') state = conclusion === 'SUCCESS' ? 'success' : 'failure';
else state = 'failure';
} else {
const status = String(match.state ?? '').toUpperCase();
state = status === 'SUCCESS' ? 'success' : ['PENDING','EXPECTED'].includes(status) ? 'pending' : 'failure';
}
return { ...required, state };
});
return {
base: fullSha(pr.baseRefOid, 'base SHA'), head: fullSha(pr.headRefOid, 'head SHA'),
pullRequestState: pr.state as RemoteMergeState['pullRequestState'], mergeable: pr.mergeable as RemoteMergeState['mergeable'],
rulesKnown, atomicBaseGuard, mergeQueue, requiredChecks, alreadyFixed: await this.#alreadyFixed(signal),
...(typeof pr.url === 'string' && pr.url.length <= 2048 && /^https:\/\//.test(pr.url) ? { url: pr.url } : {}),
};
}
async inspect(options: { fresh?: boolean; timeoutMs?: number; signal?: AbortSignal } = {}): Promise<RemoteMergeState> {
const timeoutMs = options.timeoutMs ?? MERGE_INSPECTION_TIMEOUT_MS;
if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > MERGE_INSPECTION_TIMEOUT_MS) throw new Error('Invalid GitHub inspection timeout.');
if (!options.fresh && this.#cache && this.#cache.expiresAt > Date.now()) return this.#cache.state;
const generation = this.#generation;
if (!options.fresh && this.#inflight?.generation === generation) return this.#inflight.promise;
const timeout = new AbortController();
const timer = setTimeout(() => timeout.abort(new Error('GitHub merge-state inspection timed out.')), timeoutMs);
const signal = options.signal ? AbortSignal.any([options.signal, timeout.signal]) : timeout.signal;
const attempt = this.#inspectNow(signal).catch(error => {
if (timeout.signal.aborted) throw timeout.signal.reason;
if (options.signal?.aborted) throw options.signal.reason;
throw error;
}).then(state => {
if (this.#generation === generation) this.#cache = { expiresAt: Date.now() + 5_000, state };
return state;
}).finally(() => { clearTimeout(timer); if (this.#inflight?.promise === attempt) this.#inflight = null; });
if (!options.fresh) this.#inflight = { generation, promise: attempt };
return attempt;
}
async queueWatermark(expectedHead: string, options: { signal?: AbortSignal; timeoutMs?: number } = {}): Promise<string | null> {
fullSha(expectedHead, 'expected head SHA');
const timeoutMs = options.timeoutMs ?? 6_000;
if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > MERGE_INSPECTION_TIMEOUT_MS) throw new Error('Invalid GitHub queue watermark timeout.');
const [owner, name] = this.config.repository.split('/') as [string, string];
const query = `query($owner:String!,$name:String!,$number:Int!){repository(owner:$owner,name:$name){pullRequest(number:$number){number headRefOid timelineItems(last:1,itemTypes:[ADDED_TO_MERGE_QUEUE_EVENT,REMOVED_FROM_MERGE_QUEUE_EVENT]){edges{cursor node{id}}}}}}`;
const timeout = new AbortController();
const timer = setTimeout(() => timeout.abort(new Error('GitHub merge-queue watermark timed out.')), timeoutMs);
const signal = options.signal ? AbortSignal.any([options.signal, timeout.signal]) : timeout.signal;
try {
if (options.signal?.aborted) throw options.signal.reason;
const response = await this.#json(['api','graphql','-f',`query=${query}`,'-f',`owner=${owner}`,'-f',`name=${name}`,'-F',`number=${this.config.pullRequest}`], signal) as {
data?: { repository?: { pullRequest?: { number?: unknown; headRefOid?: unknown; timelineItems?: { edges?: unknown } } | null } | null };
errors?: unknown;
};
if (signal.aborted) throw signal.reason;
if (Object.hasOwn(response, 'errors') && (!Array.isArray(response.errors) || response.errors.length > 0)) throw new Error('GitHub returned merge-queue watermark data with errors.');
const pull = response.data?.repository?.pullRequest;
if (!pull || pull.number !== this.config.pullRequest || fullSha(pull.headRefOid, 'queue watermark head SHA') !== expectedHead || !Array.isArray(pull.timelineItems?.edges))
throw new Error('GitHub returned an incomplete merge-queue watermark.');
const edges = pull.timelineItems.edges;
if (edges.length > 1) throw new Error('GitHub returned an invalid merge-queue watermark.');
const edge = edges[0];
if (edge === undefined) return null;
if (!edge || typeof edge !== 'object' || Array.isArray(edge) || typeof (edge as { cursor?: unknown }).cursor !== 'string' || !(edge as { cursor: string }).cursor ||
!(edge as { node?: unknown }).node || typeof (edge as { node: unknown }).node !== 'object' || Array.isArray((edge as { node: unknown }).node) ||
typeof ((edge as { node: { id?: unknown } }).node.id) !== 'string' || !(edge as { node: { id: string } }).node.id)
throw new Error('GitHub returned an invalid merge-queue watermark.');
return (edge as { cursor: string }).cursor;
} catch (error) {
if (options.signal?.aborted) throw options.signal.reason;
if (timeout.signal.aborted && !options.signal?.aborted) throw new Error('GitHub merge-queue watermark timed out.');
throw error;
} finally { clearTimeout(timer); }
}
async inspectQueue(expectedHead: string, options: { signal?: AbortSignal; timeoutMs?: number; afterCursor?: string | null } = {}): Promise<MergeQueueObservation> {
fullSha(expectedHead, 'expected head SHA');
const timeoutMs = options.timeoutMs ?? MERGE_INSPECTION_TIMEOUT_MS;
if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > MERGE_INSPECTION_TIMEOUT_MS) throw new Error('Invalid GitHub queue inspection timeout.');
const correlated = Object.hasOwn(options, 'afterCursor');
if (options.afterCursor !== undefined && options.afterCursor !== null && (typeof options.afterCursor !== 'string' || !options.afterCursor || options.afterCursor.length > 512))
throw new Error('Invalid merge-queue event cursor.');
const [owner, name] = this.config.repository.split('/') as [string, string];
const query = `query($owner:String!,$name:String!,$number:Int!,$after:String){repository(owner:$owner,name:$name){pullRequest(number:$number){number headRefOid state mergedAt mergeQueueEntry{id state position enqueuedAt headCommit{oid} pullRequest{number headRefOid}} timelineItems(first:100,after:$after,itemTypes:[ADDED_TO_MERGE_QUEUE_EVENT,REMOVED_FROM_MERGE_QUEUE_EVENT]){edges{cursor node{id __typename ... on AddedToMergeQueueEvent{createdAt} ... on RemovedFromMergeQueueEvent{createdAt reason beforeCommit{oid}}}} pageInfo{hasNextPage endCursor}}}}}`;
const timeout = new AbortController();
const timer = setTimeout(() => timeout.abort(new Error('GitHub merge-queue inspection timed out.')), timeoutMs);
const signal = options.signal ? AbortSignal.any([options.signal, timeout.signal]) : timeout.signal;
try {
if (options.signal?.aborted) throw options.signal.reason;
let cursor = options.afterCursor ?? null, pull: Record<string, unknown> | null = null, stable = '', page = 0;
const events: Array<{ id: string; type: unknown; createdAt: string; reason: string | undefined; beforeHead: string | undefined }> = [];
while (page++ < 10) {
const args = ['api','graphql','-f',`query=${query}`,'-f',`owner=${owner}`,'-f',`name=${name}`,'-F',`number=${this.config.pullRequest}`];
if (cursor !== null) args.push('-f', `after=${cursor}`);
const response = await this.#json(args, signal) as { data?: { repository?: { pullRequest?: Record<string, unknown> | null } | null }; errors?: unknown };
if (signal.aborted) throw signal.reason;
if (Object.hasOwn(response, 'errors') && (!Array.isArray(response.errors) || response.errors.length > 0)) throw new Error('GitHub returned merge-queue data with errors.');
const nextPull = response.data?.repository?.pullRequest;
if (!nextPull || nextPull.number !== this.config.pullRequest) throw new Error('GitHub returned an incomplete merge-queue pull request.');
const current = JSON.stringify({ number: nextPull.number, headRefOid: nextPull.headRefOid, state: nextPull.state, mergedAt: nextPull.mergedAt, mergeQueueEntry: nextPull.mergeQueueEntry });
if (stable && current !== stable) throw new Error('GitHub merge-queue state changed during paginated inspection.');
stable = current; pull = nextPull;
const timeline = nextPull.timelineItems;
if (!timeline || typeof timeline !== 'object' || Array.isArray(timeline)) throw new Error('GitHub returned incomplete merge-queue history.');
const value = timeline as { edges?: unknown; pageInfo?: { hasNextPage?: unknown; endCursor?: unknown } };
if (!Array.isArray(value.edges) || !value.pageInfo || typeof value.pageInfo.hasNextPage !== 'boolean' ||
(value.pageInfo.endCursor !== null && typeof value.pageInfo.endCursor !== 'string')) throw new Error('GitHub returned incomplete merge-queue pagination.');
for (const edge of value.edges) {
if (!edge || typeof edge !== 'object' || Array.isArray(edge) || typeof (edge as { cursor?: unknown }).cursor !== 'string' || !(edge as { cursor: string }).cursor)
throw new Error('GitHub returned a malformed merge-queue edge.');
const event = (edge as { node?: unknown }).node;
if (!event || typeof event !== 'object' || Array.isArray(event)) throw new Error('GitHub returned a malformed merge-queue event.');
const node = event as { id?: unknown; __typename?: unknown; createdAt?: unknown; reason?: unknown; beforeCommit?: { oid?: unknown } | null };
if (typeof node.id !== 'string' || !node.id || node.id.length > 512) throw new Error('GitHub returned a merge-queue event without stable identity.');
if (!['AddedToMergeQueueEvent','RemovedFromMergeQueueEvent'].includes(String(node.__typename))) throw new Error('GitHub returned an unknown merge-queue event.');
const createdAt = timestamp(node.createdAt, 'merge-queue event time');
if (node.__typename === 'RemovedFromMergeQueueEvent' && (typeof node.reason !== 'string' || !node.reason.trim())) throw new Error('GitHub returned a merge-queue removal without a reason.');
const beforeHead = node.__typename === 'RemovedFromMergeQueueEvent' ? fullSha(node.beforeCommit?.oid, 'removed merge-queue head SHA') : undefined;
events.push({ id: node.id, type: node.__typename, createdAt, reason: node.reason as string | undefined, beforeHead });
}
if (!value.pageInfo.hasNextPage) break;
if (page === 10 || typeof value.pageInfo.endCursor !== 'string' || !value.pageInfo.endCursor) throw new Error('GitHub merge-queue history exceeded the inspection limit.');
cursor = value.pageInfo.endCursor;
}
if (!pull || pull.number !== this.config.pullRequest) throw new Error('GitHub returned an incomplete merge-queue pull request.');
const reviewedHead = fullSha(pull.headRefOid, 'queue pull request head SHA');
if (reviewedHead !== expectedHead) throw new Error('The pull request head changed after review.');
if (!['OPEN','CLOSED','MERGED'].includes(String(pull.state))) throw new Error('GitHub returned an invalid queue pull request state.');
if (!Object.hasOwn(pull, 'mergedAt') || (pull.mergedAt !== null && typeof pull.mergedAt !== 'string')) throw new Error('GitHub returned invalid merge completion data.');
if (!Object.hasOwn(pull, 'mergeQueueEntry')) throw new Error('GitHub returned incomplete merge-queue data.');
const entry = pull.mergeQueueEntry;
const attemptEvents = events;
const addCount = attemptEvents.filter(event => event.type === 'AddedToMergeQueueEvent').length;
const hasCurrentAdd = addCount === 1 && attemptEvents[0]?.type === 'AddedToMergeQueueEvent';
const singleSequence = hasCurrentAdd && (attemptEvents.length === 1 || (attemptEvents.length === 2 && attemptEvents[1]?.type === 'RemovedFromMergeQueueEvent'));
if (correlated && !singleSequence) throw new Error(addCount > 1 ? 'GitHub returned multiple enqueue sequences after the current attempt cursor.' : 'GitHub did not return one complete enqueue sequence for the current attempt.');
if (pull.state === 'MERGED') {
if (entry !== null) throw new Error('GitHub returned an active queue entry for a merged pull request.');
return { state: 'merged', reviewedHead, mergedAt: timestamp(pull.mergedAt, 'merge completion time') };
}
if (pull.mergedAt !== null) throw new Error('GitHub returned inconsistent merge completion data.');
if (entry !== null) {
if (pull.state !== 'OPEN' || !entry || typeof entry !== 'object' || Array.isArray(entry)) throw new Error('GitHub returned an invalid merge-queue entry.');
const value = entry as { id?: unknown; state?: unknown; position?: unknown; enqueuedAt?: unknown; headCommit?: { oid?: unknown } | null; pullRequest?: { number?: unknown; headRefOid?: unknown } | null };
if (typeof value.id !== 'string' || !value.id || !['AWAITING_CHECKS','LOCKED','MERGEABLE','QUEUED','UNMERGEABLE'].includes(String(value.state)) || !Number.isSafeInteger(value.position) || (value.position as number) < 0)
throw new Error('GitHub returned an invalid merge-queue entry.');
const enqueuedAt = timestamp(value.enqueuedAt, 'merge-queue entry time');
if (correlated && attemptEvents.length !== 1) throw new Error('GitHub returned an ambiguous active event sequence for the current enqueue attempt.');
const queueHead = fullSha(value.headCommit?.oid, 'merge-queue head SHA');
const entryHead = fullSha(value.pullRequest?.headRefOid, 'merge-queue entry pull request head SHA');
if (value.pullRequest?.number !== this.config.pullRequest || queueHead !== expectedHead || entryHead !== expectedHead) throw new Error('The merge-queue entry does not match the reviewed pull request head.');
if (value.state === 'UNMERGEABLE') return { state: 'failed', reviewedHead, entryId: value.id, reason: 'GitHub reported the merge queue entry as unmergeable.' };
return {
state: 'queued', reviewedHead, entryId: value.id, phase: value.state as MergeQueueEntryPhase,
position: value.position as number, enqueuedAt, queueHead,
};
}
if (correlated && attemptEvents.length === 0) throw new Error('GitHub did not return an event for the current enqueue attempt.');
const last = (correlated ? attemptEvents : events).at(-1);
if (!last || last.type !== 'RemovedFromMergeQueueEvent') throw new Error('GitHub did not confirm a queued, removed, failed, or merged state.');
if (last.beforeHead !== expectedHead) throw new Error('The merge-queue removal does not match the reviewed pull request head.');
if (correlated && (attemptEvents.length !== 2 || attemptEvents[1]?.type !== 'RemovedFromMergeQueueEvent')) throw new Error('GitHub returned an ambiguous terminal event sequence for the current enqueue attempt.');
return { state: 'removed', reviewedHead, removedAt: last.createdAt, reason: last.reason! };
} catch (error) {
if (options.signal?.aborted) throw options.signal.reason;
if (timeout.signal.aborted && !options.signal?.aborted) throw new Error('GitHub merge-queue inspection timed out.');
throw error;
} finally { clearTimeout(timer); }
}
async merge(expectedHead: string, options: { signal?: AbortSignal } = {}): Promise<MergeResult> {
fullSha(expectedHead, 'expected head SHA');
const flag = this.config.method === 'squash' ? '--squash' : this.config.method === 'rebase' ? '--rebase' : '--merge';
this.#generation++;
this.#cache = null;
try {
if (options.signal?.aborted) throw options.signal.reason;
await this.run(['pr','merge',String(this.config.pullRequest),'--repo',this.config.repository,flag,'--match-head-commit',expectedHead], { signal: options.signal });
return { url: `https://github.com/${this.config.repository}/pull/${this.config.pullRequest}` };
} catch (error) {
if (error instanceof MergeSubmissionError) throw error;
const message = error instanceof Error ? error.message : 'GitHub merge submission failed with an unknown outcome.';
const outcome = !options.signal?.aborted && confirmedMergeRefusal(message) ? 'refused' : 'unknown';
throw new MergeSubmissionError(message, outcome, { cause: error });
} finally { this.#generation++; this.#cache = null; }
}
}