Open History to see the last commit
1import * as Schema from "effect/Schema";
2import * as Effect from "effect/Effect";
3import * as HttpServerRespondable from "effect/http/HttpServerRespondable";
4import * as HttpServerResponse from "effect/http/HttpServerResponse";
5
6import {
7 ForwardCompatibleArray,
8 IsoDateTime,
9 NonNegativeInt,
10 PositiveInt,
11 ProjectId,
12 ThreadId,
13 TrimmedNonEmptyString,
14} from "./baseSchemas.ts";
15import { SourceControlProviderKind } from "./sourceControl.ts";
16
17export const PullRequestInvolvement = Schema.Literals(["all", "reviewing", "authored"]);
18export type PullRequestInvolvement = typeof PullRequestInvolvement.Type;
19
20export const PullRequestState = Schema.Literals(["open", "closed", "merged"]);
21export type PullRequestState = typeof PullRequestState.Type;
22
23export const PullRequestListState = Schema.Literals(["all", "open", "closed", "merged"]);
24export type PullRequestListState = typeof PullRequestListState.Type;
25
26export const PullRequestReviewDecision = Schema.Literals([
27 "approved",
28 "changes-requested",
29 "review-required",
30]);
31export type PullRequestReviewDecision = typeof PullRequestReviewDecision.Type;
32
33const PullRequestQualifierValue = TrimmedNonEmptyString.check(Schema.isMaxLength(200));
34const PullRequestQualifierValues = Schema.Array(PullRequestQualifierValue).check(
35 Schema.isMaxLength(10),
36);
37
38export const PullRequestListFilters = Schema.Struct({
39 draft: Schema.optional(Schema.Literals(["only", "hide"])),
40 review: Schema.optional(
41 Schema.Literals(["approved", "changes-requested", "review-required", "none"]),
42 ),
43 checks: Schema.optional(Schema.Literals(["passing", "failing"])),
44 /** GitHub label qualifiers: every group must match; any name within a group suffices. */
45 labels: Schema.optional(Schema.Array(PullRequestQualifierValues).check(Schema.isMaxLength(10))),
46 excludedLabels: Schema.optional(PullRequestQualifierValues),
47 author: Schema.optional(PullRequestQualifierValue),
48});
49export type PullRequestListFilters = typeof PullRequestListFilters.Type;
50
51export const PullRequestChecksState = Schema.Literals(["passing", "failing", "pending"]);
52export type PullRequestChecksState = typeof PullRequestChecksState.Type;
53
54export const PullRequestMergeability = Schema.Literals(["mergeable", "conflicting", "unknown"]);
55export type PullRequestMergeability = typeof PullRequestMergeability.Type;
56
57/** `fast-forward` refuses unless the head contains the base, where `rebase` rewrites the branch onto it. */
58export const PullRequestMergeMethod = Schema.Literals([
59 "merge",
60 "squash",
61 "rebase",
62 "fast-forward",
63]);
64export type PullRequestMergeMethod = typeof PullRequestMergeMethod.Type;
65
66export const PullRequestAction = Schema.Literals([
67 "merge",
68 "ready",
69 "draft",
70 "close",
71 "reopen",
72 "delete-branch",
73 "update-branch",
74 "enable-auto-merge",
75 "disable-auto-merge",
76 "revert",
77 "approve-workflows",
78]);
79export type PullRequestAction = typeof PullRequestAction.Type;
80
81export const PullRequestUpdateMethod = Schema.Literals(["merge", "rebase"]);
82export type PullRequestUpdateMethod = typeof PullRequestUpdateMethod.Type;
83
84export const PullRequestBaseComparison = Schema.Literals(["up-to-date", "behind", "unknown"]);
85export type PullRequestBaseComparison = typeof PullRequestBaseComparison.Type;
86
87export const PullRequestActor = Schema.Struct({
88 isBot: Schema.optional(Schema.Boolean),
89 login: TrimmedNonEmptyString,
90 name: Schema.NullOr(Schema.String),
91 avatarUrl: Schema.NullOr(Schema.String),
92});
93export type PullRequestActor = typeof PullRequestActor.Type;
94
95export const PullRequestLabel = Schema.Struct({
96 name: TrimmedNonEmptyString,
97 color: Schema.NullOr(Schema.String),
98 description: Schema.optional(Schema.NullOr(Schema.String)),
99});
100export type PullRequestLabel = typeof PullRequestLabel.Type;
101
102export const PullRequestCheckStatus = Schema.Literals([
103 "pending",
104 "action-required",
105 "success",
106 "failure",
107 "skipped",
108 "neutral",
109 "cancelled",
110]);
111export type PullRequestCheckStatus = typeof PullRequestCheckStatus.Type;
112
113export const PullRequestCheck = Schema.Struct({
114 name: TrimmedNonEmptyString,
115 status: PullRequestCheckStatus,
116 description: Schema.NullOr(Schema.String),
117 url: Schema.NullOr(Schema.String),
118 required: Schema.optional(Schema.Boolean),
119 /**
120 * Not a check: it stands for ones the host could not list, such as workflow runs awaiting
121 * approval when that read fails, so nothing waits on it or counts it as passing.
122 */
123 placeholder: Schema.optional(Schema.Boolean),
124});
125export type PullRequestCheck = typeof PullRequestCheck.Type;
126
127export const PullRequestReactionContent = Schema.Literals([
128 "thumbs-up",
129 "thumbs-down",
130 "laugh",
131 "hooray",
132 "confused",
133 "heart",
134 "rocket",
135 "eyes",
136]);
137export type PullRequestReactionContent = typeof PullRequestReactionContent.Type;
138
139export const PullRequestReaction = Schema.Struct({
140 content: PullRequestReactionContent,
141 count: PositiveInt,
142 /** Excludes the viewer's login when viewerHasReacted; count still includes them. */
143 actors: Schema.Array(TrimmedNonEmptyString),
144 viewerHasReacted: Schema.Boolean,
145});
146export type PullRequestReaction = typeof PullRequestReaction.Type;
147
148export const PullRequestCommentKind = Schema.Literals([
149 "issue-comment",
150 "review-comment",
151 "review",
152]);
153export type PullRequestCommentKind = typeof PullRequestCommentKind.Type;
154
155export const PullRequestComment = Schema.Struct({
156 id: TrimmedNonEmptyString,
157 kind: PullRequestCommentKind,
158 author: Schema.NullOr(PullRequestActor),
159 body: Schema.String,
160 createdAt: IsoDateTime,
161 editedAt: Schema.optional(Schema.NullOr(IsoDateTime)),
162 url: Schema.NullOr(Schema.String),
163 path: Schema.NullOr(Schema.String),
164 reviewState: Schema.NullOr(Schema.String),
165 reactions: Schema.optional(Schema.Array(PullRequestReaction)),
166 canEdit: Schema.optional(Schema.Boolean),
167});
168export type PullRequestComment = typeof PullRequestComment.Type;
169
170export const PullRequestDiffSide = Schema.Literals(["left", "right"]);
171export type PullRequestDiffSide = typeof PullRequestDiffSide.Type;
172
173export const PullRequestReviewVerdict = Schema.Literals(["comment", "approve", "request-changes"]);
174export type PullRequestReviewVerdict = typeof PullRequestReviewVerdict.Type;
175
176export const PullRequestThreadComment = Schema.Struct({
177 id: TrimmedNonEmptyString,
178 author: Schema.NullOr(PullRequestActor),
179 body: Schema.String,
180 createdAt: IsoDateTime,
181 editedAt: Schema.optional(Schema.NullOr(IsoDateTime)),
182 url: Schema.NullOr(Schema.String),
183 /** The review that posted the comment, so a link to a review with no text finds its comments. */
184 reviewUrl: Schema.optional(Schema.NullOr(Schema.String)),
185 reactions: Schema.optional(Schema.Array(PullRequestReaction)),
186 canEdit: Schema.optional(Schema.Boolean),
187});
188export type PullRequestThreadComment = typeof PullRequestThreadComment.Type;
189
190export const PullRequestReviewThread = Schema.Struct({
191 id: TrimmedNonEmptyString,
192 path: TrimmedNonEmptyString,
193 line: Schema.NullOr(PositiveInt),
194 side: PullRequestDiffSide,
195 isResolved: Schema.Boolean,
196 isOutdated: Schema.Boolean,
197 comments: Schema.Array(PullRequestThreadComment),
198 commentCount: Schema.optional(NonNegativeInt),
199 nextCommentsCursor: Schema.optional(TrimmedNonEmptyString),
200 /** Can only narrow repository-wide resolve permission. Absent when unreported. */
201 canResolve: Schema.optional(Schema.Boolean),
202});
203export type PullRequestReviewThread = typeof PullRequestReviewThread.Type;
204
205/** A thread on the change request as a whole, such as a GitLab overview thread. */
206export const PullRequestOverviewThread = Schema.Struct({
207 ...PullRequestReviewThread.fields,
208 path: Schema.Null,
209 line: Schema.Null,
210});
211export type PullRequestOverviewThread = typeof PullRequestOverviewThread.Type;
212
213export type PullRequestConversationThread = PullRequestReviewThread | PullRequestOverviewThread;
214
215export const PullRequestReviewerKind = Schema.Literals(["user", "team"]);
216export type PullRequestReviewerKind = typeof PullRequestReviewerKind.Type;
217
218export const PullRequestReviewerCandidate = Schema.Struct({
219 ...PullRequestActor.fields,
220 id: TrimmedNonEmptyString,
221 kind: PullRequestReviewerKind,
222 isRequested: Schema.Boolean,
223});
224export type PullRequestReviewerCandidate = typeof PullRequestReviewerCandidate.Type;
225
226export const PullRequestReviewerCandidateList = Schema.Struct({
227 candidates: Schema.Array(PullRequestReviewerCandidate),
228 truncated: Schema.Boolean,
229});
230export type PullRequestReviewerCandidateList = typeof PullRequestReviewerCandidateList.Type;
231
232export const PullRequestLabelCandidate = Schema.Struct({
233 ...PullRequestLabel.fields,
234 description: Schema.NullOr(Schema.String),
235 isApplied: Schema.Boolean,
236});
237export type PullRequestLabelCandidate = typeof PullRequestLabelCandidate.Type;
238
239export const PullRequestLabelCandidateList = Schema.Struct({
240 candidates: Schema.Array(PullRequestLabelCandidate),
241 truncated: Schema.Boolean,
242});
243export type PullRequestLabelCandidateList = typeof PullRequestLabelCandidateList.Type;
244
245export const PullRequestCommit = Schema.Struct({
246 oid: TrimmedNonEmptyString,
247 messageHeadline: Schema.String,
248 committedDate: IsoDateTime,
249 additions: Schema.optional(NonNegativeInt),
250 deletions: Schema.optional(NonNegativeInt),
251 authors: Schema.optional(Schema.Array(PullRequestActor)),
252});
253export type PullRequestCommit = typeof PullRequestCommit.Type;
254
255export const PullRequestReviewCapabilities = Schema.Struct({
256 inlineComment: Schema.Boolean,
257 /**
258 * An inline comment can cover a range of lines rather than its last one. Absent, as from a
259 * server that predates it, means one line.
260 */
261 rangeComment: Schema.optional(Schema.Boolean),
262 reply: Schema.Boolean,
263 resolve: Schema.Boolean,
264 verdicts: ForwardCompatibleArray(PullRequestReviewVerdict),
265});
266export type PullRequestReviewCapabilities = typeof PullRequestReviewCapabilities.Type;
267
268export const PullRequestEditCapabilities = Schema.Struct({
269 changeRequest: Schema.Boolean,
270 comment: Schema.Boolean,
271 maintainerEdits: Schema.optional(Schema.Boolean),
272});
273export type PullRequestEditCapabilities = typeof PullRequestEditCapabilities.Type;
274
275export const PullRequestReviewerCapabilities = Schema.Struct({
276 request: Schema.Boolean,
277 listCandidates: Schema.Boolean,
278 /**
279 * Reviewer candidates take a `query` the host matches past the first page. Absent, as from a
280 * server that predates it, means the client narrows the loaded page itself.
281 */
282 searchCandidates: Schema.optional(Schema.Boolean),
283});
284export type PullRequestReviewerCapabilities = typeof PullRequestReviewerCapabilities.Type;
285
286export const PullRequestViewedFilesStore = Schema.Literals(["host", "environment"]);
287export type PullRequestViewedFilesStore = typeof PullRequestViewedFilesStore.Type;
288
289/** `#` references issues (and GitHub pull requests); `!` references GitLab merge requests. */
290export const PullRequestReferenceSigil = Schema.Literals(["#", "!"]);
291export type PullRequestReferenceSigil = typeof PullRequestReferenceSigil.Type;
292
293export const PullRequestCapabilities = Schema.Struct({
294 diff: Schema.Boolean,
295 comment: Schema.Boolean,
296 actions: ForwardCompatibleArray(PullRequestAction),
297 mergeMethods: ForwardCompatibleArray(PullRequestMergeMethod),
298 deleteBranch: Schema.optional(Schema.Boolean),
299 /**
300 * Absent where it cannot at all, which is every host that has not said otherwise — so a
301 * provider that says nothing offers nothing.
302 */
303 updateMethods: Schema.optional(ForwardCompatibleArray(PullRequestUpdateMethod)),
304 search: Schema.Boolean,
305 reactions: Schema.optional(Schema.Boolean),
306 viewedFiles: Schema.optional(PullRequestViewedFilesStore),
307 review: PullRequestReviewCapabilities,
308 reviewers: PullRequestReviewerCapabilities,
309 edit: Schema.optional(PullRequestEditCapabilities),
310 stacks: Schema.optional(Schema.Boolean),
311 stackActions: Schema.optional(Schema.Boolean),
312 labels: Schema.optional(Schema.Boolean),
313 /** The host searches the repository's users, so composers can complete `@login`. */
314 mentions: Schema.optional(Schema.Boolean),
315 /** The sigils whose issue and change request references composers can complete. */
316 referenceSigils: Schema.optional(ForwardCompatibleArray(PullRequestReferenceSigil)),
317 /**
318 * Every head gets at least one check, so a head that has gone a while without any means none
319 * reported rather than that the repository runs none. Absent means an empty list says nothing.
320 */
321 checksAlwaysReport: Schema.optional(Schema.Boolean),
322});
323export type PullRequestCapabilities = typeof PullRequestCapabilities.Type;
324
325/** Unreported host permissions are granted. */
326export const PullRequestViewerPermissions = Schema.Struct({
327 stackRebase: Schema.optional(Schema.Boolean),
328 actions: ForwardCompatibleArray(PullRequestAction),
329 comment: Schema.Boolean,
330 resolve: Schema.Boolean,
331 verdicts: ForwardCompatibleArray(PullRequestReviewVerdict),
332 requestReviewers: Schema.Boolean,
333 updateMethods: Schema.optional(ForwardCompatibleArray(PullRequestUpdateMethod)),
334 labels: Schema.optional(Schema.Boolean),
335 editChangeRequest: Schema.optional(Schema.Boolean),
336 maintainerEdits: Schema.optional(Schema.Boolean),
337});
338export type PullRequestViewerPermissions = typeof PullRequestViewerPermissions.Type;
339
340export const PullRequestMergeCapabilities = Schema.Struct({
341 merge: Schema.Boolean,
342 squash: Schema.Boolean,
343 rebase: Schema.Boolean,
344 /** Optional so servers that predate it still decode; absent means not allowed. */
345 "fast-forward": Schema.optional(Schema.Boolean),
346});
347export type PullRequestMergeCapabilities = typeof PullRequestMergeCapabilities.Type;
348
349export const PullRequestStackMembership = Schema.Struct({
350 number: PositiveInt,
351 position: PositiveInt,
352 size: PositiveInt,
353 base: TrimmedNonEmptyString,
354});
355export type PullRequestStackMembership = typeof PullRequestStackMembership.Type;
356
357export const PullRequestListEntry = Schema.Struct({
358 stack: Schema.optional(PullRequestStackMembership),
359 provider: SourceControlProviderKind,
360 host: TrimmedNonEmptyString,
361 projectId: ProjectId,
362 projectTitle: TrimmedNonEmptyString,
363 repository: TrimmedNonEmptyString,
364 number: PositiveInt,
365 title: TrimmedNonEmptyString,
366 url: TrimmedNonEmptyString,
367 author: Schema.NullOr(PullRequestActor),
368 headBranch: TrimmedNonEmptyString,
369 baseBranch: TrimmedNonEmptyString,
370 state: PullRequestState,
371 isDraft: Schema.Boolean,
372 mergeability: PullRequestMergeability,
373 /** Zero until fetched through `PullRequestListStatsInput`; GitHub listings omit counts. */
374 additions: NonNegativeInt,
375 deletions: NonNegativeInt,
376 createdAt: IsoDateTime,
377 updatedAt: IsoDateTime,
378 observedAt: Schema.optional(Schema.Finite),
379 viewerReviewRequested: Schema.Boolean,
380 labels: Schema.Array(PullRequestLabel),
381 reviewDecision: Schema.optional(PullRequestReviewDecision),
382 checksState: Schema.optional(PullRequestChecksState),
383});
384export type PullRequestListEntry = typeof PullRequestListEntry.Type;
385
386export const PullRequestListCursors = Schema.Record(
387 TrimmedNonEmptyString,
388 TrimmedNonEmptyString.check(Schema.isMaxLength(4096)),
389);
390export type PullRequestListCursors = typeof PullRequestListCursors.Type;
391
392export const PULL_REQUEST_LIST_PROJECT_LIMIT = 100;
393
394export const PullRequestListInput = Schema.Struct({
395 state: PullRequestListState,
396 involvement: Schema.optional(PullRequestInvolvement),
397 filters: Schema.optional(PullRequestListFilters),
398 projectId: Schema.optional(ProjectId),
399 projectIds: Schema.optional(
400 Schema.Array(ProjectId).check(Schema.isMaxLength(PULL_REQUEST_LIST_PROJECT_LIMIT)),
401 ),
402 host: Schema.optional(TrimmedNonEmptyString),
403 limit: Schema.optional(Schema.Int.check(Schema.isBetween({ minimum: 1, maximum: 500 }))),
404 cursors: Schema.optional(PullRequestListCursors),
405 query: Schema.optional(TrimmedNonEmptyString.check(Schema.isMaxLength(200))),
406});
407export type PullRequestListInput = typeof PullRequestListInput.Type;
408
409export const PullRequestProviderSummary = Schema.Struct({
410 host: TrimmedNonEmptyString,
411 kind: SourceControlProviderKind,
412 searchesOnHost: Schema.Boolean,
413 actions: Schema.optional(ForwardCompatibleArray(PullRequestAction)),
414 projectCount: PositiveInt,
415 /** SSH checkouts can resolve to an HTTP authority different from their stored identity. */
416 projectIds: Schema.optional(Schema.Array(ProjectId)),
417 configured: Schema.Boolean,
418 detail: Schema.NullOr(TrimmedNonEmptyString),
419});
420export type PullRequestProviderSummary = typeof PullRequestProviderSummary.Type;
421
422export const PullRequestListProjectError = Schema.Struct({
423 projectId: ProjectId,
424 projectTitle: TrimmedNonEmptyString,
425 message: TrimmedNonEmptyString,
426});
427export type PullRequestListProjectError = typeof PullRequestListProjectError.Type;
428
429export const PullRequestListResult = Schema.Struct({
430 /** Unreadable hosts are absent; JSON codecs reject optional record values. */
431 viewers: Schema.Record(TrimmedNonEmptyString, TrimmedNonEmptyString),
432 providers: Schema.Array(PullRequestProviderSummary),
433 /** Re-sort after appending: one repository's older slice may outrank another's existing rows. */
434 entries: Schema.Array(PullRequestListEntry),
435 errors: Schema.Array(PullRequestListProjectError),
436 truncated: Schema.Boolean,
437 nextCursors: PullRequestListCursors,
438});
439export type PullRequestListResult = typeof PullRequestListResult.Type;
440
441export const PullRequestRef = Schema.Struct({
442 projectId: ProjectId,
443 host: Schema.optional(TrimmedNonEmptyString),
444 expectedAccountId: Schema.optional(TrimmedNonEmptyString),
445 allowStale: Schema.optional(Schema.Boolean),
446 repository: TrimmedNonEmptyString,
447 number: PositiveInt,
448});
449export type PullRequestRef = typeof PullRequestRef.Type;
450
451/** `query` asks the host for matches past the first page of candidates. */
452export const PullRequestReviewerCandidatesInput = Schema.Struct({
453 ...PullRequestRef.fields,
454 query: Schema.optional(TrimmedNonEmptyString.check(Schema.isMaxLength(100))),
455});
456export type PullRequestReviewerCandidatesInput = typeof PullRequestReviewerCandidatesInput.Type;
457
458export const PullRequestRoutingIdentityInput = Schema.Struct({
459 host: TrimmedNonEmptyString,
460});
461export type PullRequestRoutingIdentityInput = typeof PullRequestRoutingIdentityInput.Type;
462
463export const PullRequestRoutingIdentityResult = Schema.Struct({
464 accountId: TrimmedNonEmptyString,
465 host: TrimmedNonEmptyString,
466 provider: SourceControlProviderKind,
467 viewer: TrimmedNonEmptyString,
468});
469export type PullRequestRoutingIdentityResult = typeof PullRequestRoutingIdentityResult.Type;
470
471export const PullRequestRoutingResult = Schema.Struct({
472 accountId: TrimmedNonEmptyString,
473 host: TrimmedNonEmptyString,
474 provider: SourceControlProviderKind,
475 viewer: TrimmedNonEmptyString,
476 projectTitle: TrimmedNonEmptyString,
477 workspaceRoot: TrimmedNonEmptyString,
478});
479export type PullRequestRoutingResult = typeof PullRequestRoutingResult.Type;
480
481export const PullRequestLinkedThreadsResult = Schema.Struct({
482 threads: Schema.Array(
483 Schema.Struct({
484 id: ThreadId,
485 projectId: ProjectId,
486 title: Schema.String,
487 archivedAt: Schema.NullOr(IsoDateTime),
488 settled: Schema.optionalKey(Schema.Boolean),
489 }),
490 ),
491});
492export type PullRequestLinkedThreadsResult = typeof PullRequestLinkedThreadsResult.Type;
493
494export const PullRequestPreview = Schema.Struct({
495 projectId: ProjectId,
496 repository: TrimmedNonEmptyString,
497 number: PositiveInt,
498 title: TrimmedNonEmptyString,
499 url: TrimmedNonEmptyString,
500 author: Schema.NullOr(PullRequestActor),
501 state: PullRequestState,
502 isDraft: Schema.Boolean,
503 createdAt: IsoDateTime,
504 updatedAt: Schema.optional(IsoDateTime),
505 observedAt: Schema.optional(Schema.Finite),
506});
507export type PullRequestPreview = typeof PullRequestPreview.Type;
508
509export const PullRequestSummary = Schema.Struct({
510 provider: SourceControlProviderKind,
511 projectId: ProjectId,
512 repository: TrimmedNonEmptyString,
513 number: PositiveInt,
514 title: TrimmedNonEmptyString,
515 url: TrimmedNonEmptyString,
516 state: PullRequestState,
517 isDraft: Schema.optional(Schema.Boolean),
518 headBranch: TrimmedNonEmptyString,
519 baseBranch: TrimmedNonEmptyString,
520 closedAt: Schema.optional(Schema.NullOr(Schema.String)),
521 mergedAt: Schema.optional(Schema.NullOr(Schema.String)),
522 updatedAt: IsoDateTime,
523 observedAt: Schema.optional(Schema.Finite),
524 author: Schema.optional(Schema.NullOr(PullRequestActor)),
525 additions: Schema.optional(NonNegativeInt),
526 deletions: Schema.optional(NonNegativeInt),
527 changedFiles: Schema.optional(NonNegativeInt),
528 reviewDecision: Schema.optional(Schema.NullOr(PullRequestReviewDecision)),
529 checksState: Schema.optional(Schema.NullOr(PullRequestChecksState)),
530 mergeability: Schema.optional(PullRequestMergeability),
531 /** Null when the host says the pull request is in no stack; absent when the read did not ask. */
532 stack: Schema.optional(Schema.NullOr(PullRequestStackMembership)),
533 headSha: Schema.optional(TrimmedNonEmptyString),
534 /** Absent means the read did not report auto-merge state, not that it is off. */
535 autoMergeEnabled: Schema.optional(Schema.Boolean),
536 autoMergeMethod: Schema.optional(PullRequestMergeMethod),
537});
538export type PullRequestSummary = typeof PullRequestSummary.Type;
539
540export const PullRequestStack = Schema.Struct({
541 id: TrimmedNonEmptyString,
542 number: PositiveInt,
543 url: TrimmedNonEmptyString,
544 base: TrimmedNonEmptyString,
545 layers: Schema.Array(
546 Schema.Struct({
547 number: PositiveInt,
548 title: Schema.optional(Schema.String),
549 isDraft: Schema.optional(Schema.Boolean),
550 headSha: Schema.optional(TrimmedNonEmptyString),
551 headBranch: TrimmedNonEmptyString,
552 state: PullRequestState,
553 }),
554 ),
555});
556export type PullRequestStack = typeof PullRequestStack.Type;
557
558export const PullRequestDiffStat = Schema.Struct({
559 projectId: ProjectId,
560 repository: TrimmedNonEmptyString,
561 number: PositiveInt,
562 additions: NonNegativeInt,
563 deletions: NonNegativeInt,
564});
565export type PullRequestDiffStat = typeof PullRequestDiffStat.Type;
566
567export const PullRequestListStatsInput = Schema.Struct({
568 refs: Schema.Array(PullRequestRef).check(Schema.isMaxLength(500)),
569});
570export type PullRequestListStatsInput = typeof PullRequestListStatsInput.Type;
571
572export const PullRequestListStatsResult = Schema.Struct({
573 stats: Schema.Array(PullRequestDiffStat),
574});
575export type PullRequestListStatsResult = typeof PullRequestListStatsResult.Type;
576
577export const PullRequestFilterOptionKind = Schema.Literals(["labels", "authors", "references"]);
578export type PullRequestFilterOptionKind = typeof PullRequestFilterOptionKind.Type;
579
580/** Scoped like `PullRequestListInput`, so the options come from the repositories it lists. */
581export const PullRequestFilterOptionsInput = Schema.Struct({
582 kind: PullRequestFilterOptionKind,
583 projectId: Schema.optional(ProjectId),
584 projectIds: Schema.optional(Schema.Array(ProjectId).check(Schema.isMaxLength(100))),
585 host: Schema.optional(TrimmedNonEmptyString),
586 query: Schema.optional(TrimmedNonEmptyString.check(Schema.isMaxLength(100))),
587 /** For `references`, the sigil typed, so a host can search only what it links. */
588 sigil: Schema.optional(PullRequestReferenceSigil),
589});
590export type PullRequestFilterOptionsInput = typeof PullRequestFilterOptionsInput.Type;
591
592/** An issue or change request a composer can reference, with the text the host links. */
593export const PullRequestReferenceCandidate = Schema.Struct({
594 reference: TrimmedNonEmptyString,
595 kind: Schema.Literals(["issue", "change-request"]),
596 number: PositiveInt,
597 title: Schema.String,
598 state: Schema.Literals(["open", "closed", "merged"]),
599});
600export type PullRequestReferenceCandidate = typeof PullRequestReferenceCandidate.Type;
601
602export const PullRequestFilterOptions = Schema.Struct({
603 labels: Schema.Array(PullRequestLabel),
604 authors: Schema.Array(PullRequestActor),
605 // Servers from before reference completion send no key.
606 references: Schema.Array(PullRequestReferenceCandidate).pipe(
607 Schema.withDecodingDefault(Effect.succeed([])),
608 ),
609 truncated: Schema.Boolean,
610});
611export type PullRequestFilterOptions = typeof PullRequestFilterOptions.Type;
612
613/**
614 * A separate request rather than a flag on the reads, so an explicit "refresh" one person
615 * presses is the only thing that spends host requests — every ordinary read shares.
616 */
617export const PullRequestInvalidateInput = Schema.Struct({
618 reference: Schema.optional(PullRequestRef),
619 filesViewedOnly: Schema.optional(Schema.Boolean),
620});
621export type PullRequestInvalidateInput = typeof PullRequestInvalidateInput.Type;
622
623export const PullRequestReportStateInput = Schema.Struct({
624 reference: PullRequestRef,
625 state: PullRequestState,
626 isDraft: Schema.optional(Schema.Boolean),
627});
628export type PullRequestReportStateInput = typeof PullRequestReportStateInput.Type;
629
630/** The host's merge queue letting go of a pull request without merging it, newest first. */
631export const PullRequestMergeQueueRemoval = Schema.Struct({
632 id: TrimmedNonEmptyString,
633 removedAt: IsoDateTime,
634 reason: Schema.NullOr(Schema.String),
635});
636export type PullRequestMergeQueueRemoval = typeof PullRequestMergeQueueRemoval.Type;
637
638export const PullRequestDetail = Schema.Struct({
639 provider: SourceControlProviderKind,
640 capabilities: PullRequestCapabilities,
641 viewerPermissions: PullRequestViewerPermissions,
642 projectId: ProjectId,
643 projectTitle: TrimmedNonEmptyString,
644 workspaceRoot: TrimmedNonEmptyString,
645 repository: TrimmedNonEmptyString,
646 number: PositiveInt,
647 title: TrimmedNonEmptyString,
648 body: Schema.String,
649 url: TrimmedNonEmptyString,
650 author: Schema.NullOr(PullRequestActor),
651 state: PullRequestState,
652 isDraft: Schema.Boolean,
653 mergeability: PullRequestMergeability,
654 additions: NonNegativeInt,
655 deletions: NonNegativeInt,
656 changedFiles: NonNegativeInt,
657 headBranch: TrimmedNonEmptyString,
658 headRepositoryNameWithOwner: Schema.optional(Schema.NullOr(TrimmedNonEmptyString)),
659 headSha: Schema.optional(TrimmedNonEmptyString),
660 baseBranch: TrimmedNonEmptyString,
661 createdAt: IsoDateTime,
662 updatedAt: IsoDateTime,
663 observedAt: Schema.optional(Schema.Finite),
664 mergedAt: Schema.NullOr(IsoDateTime),
665 closedAt: Schema.NullOr(IsoDateTime),
666 reviewers: Schema.Array(PullRequestActor),
667 labels: Schema.Array(PullRequestLabel),
668 checks: Schema.Array(PullRequestCheck),
669 mergeCapabilities: PullRequestMergeCapabilities,
670 viewer: Schema.optional(TrimmedNonEmptyString),
671 baseComparison: Schema.optional(PullRequestBaseComparison),
672 behindBy: Schema.optional(NonNegativeInt),
673 /** Absent means the host does not report auto-merge state, not that it is off. */
674 autoMergeEnabled: Schema.optional(Schema.Boolean),
675 autoMergeMethod: Schema.optional(PullRequestMergeMethod),
676 workflowApprovalsRequired: Schema.optional(NonNegativeInt),
677 /** Absent where the host has no merge queue or does not report one. */
678 mergeQueueRemoval: Schema.optional(PullRequestMergeQueueRemoval),
679 maintainerCanModify: Schema.optional(Schema.Boolean),
680});
681export type PullRequestDetail = typeof PullRequestDetail.Type;
682
683export const PullRequestChecks = Schema.Struct({
684 observedAt: Schema.optional(Schema.Finite),
685 state: PullRequestState,
686 checks: Schema.Array(PullRequestCheck),
687});
688export type PullRequestChecks = typeof PullRequestChecks.Type;
689
690export const PullRequestActivity = Schema.Struct({
691 author: Schema.optional(Schema.NullOr(PullRequestActor)),
692 reviewers: Schema.optional(Schema.Array(PullRequestActor)),
693 comments: Schema.Array(PullRequestComment),
694 commentCount: NonNegativeInt,
695 commentsTruncated: Schema.Boolean,
696 reviewThreadsTruncated: Schema.optional(Schema.Boolean),
697 reviewThreads: Schema.Array(PullRequestReviewThread),
698 // Apart from reviewThreads so clients that require a thread path still decode the activity.
699 overviewThreads: Schema.optional(Schema.Array(PullRequestOverviewThread)),
700 commits: Schema.Array(PullRequestCommit),
701 reactions: Schema.optional(Schema.Array(PullRequestReaction)),
702});
703export type PullRequestActivity = typeof PullRequestActivity.Type;
704
705export const pullRequestConversationThreads = (
706 activity: Pick<PullRequestActivity, "reviewThreads" | "overviewThreads">,
707): ReadonlyArray<PullRequestConversationThread> =>
708 activity.overviewThreads === undefined || activity.overviewThreads.length === 0
709 ? activity.reviewThreads
710 : [...activity.reviewThreads, ...activity.overviewThreads];
711
712export const PullRequestDetailView = Schema.Struct({
713 ...PullRequestDetail.fields,
714 ...PullRequestActivity.fields,
715 author: Schema.NullOr(PullRequestActor),
716 reviewers: Schema.Array(PullRequestActor),
717});
718export type PullRequestDetailView = typeof PullRequestDetailView.Type;
719
720/** GitHub refuses diffs past 300 files, so callers must page large changes. */
721export const PullRequestDiffInput = Schema.Struct({
722 ...PullRequestRef.fields,
723 cursor: Schema.optional(TrimmedNonEmptyString),
724 commit: Schema.optional(TrimmedNonEmptyString),
725});
726export type PullRequestDiffInput = typeof PullRequestDiffInput.Type;
727
728export const PullRequestOmittedFileStat = Schema.Struct({
729 path: TrimmedNonEmptyString,
730 additions: Schema.Number,
731 deletions: Schema.Number,
732});
733export type PullRequestOmittedFileStat = typeof PullRequestOmittedFileStat.Type;
734
735export const PullRequestDiffResult = Schema.Struct({
736 patch: Schema.String,
737 /** Content omitted within this slice; nextCursor separately indicates more slices. */
738 truncated: Schema.Boolean,
739 nextCursor: Schema.NullOr(TrimmedNonEmptyString),
740 omittedFileStats: Schema.optional(Schema.Array(PullRequestOmittedFileStat)),
741});
742export type PullRequestDiffResult = typeof PullRequestDiffResult.Type;
743
744export const PullRequestDiffFileContentsInput = Schema.Struct({
745 ...PullRequestRef.fields,
746 commit: Schema.optional(TrimmedNonEmptyString),
747 changeType: Schema.Literals(["change", "rename-pure", "rename-changed", "new", "deleted"]),
748 oldPath: TrimmedNonEmptyString,
749 newPath: TrimmedNonEmptyString,
750});
751export type PullRequestDiffFileContentsInput = typeof PullRequestDiffFileContentsInput.Type;
752
753export const PullRequestDiffFileContentsResult = Schema.Struct({
754 oldContents: Schema.String,
755 newContents: Schema.String,
756});
757export type PullRequestDiffFileContentsResult = typeof PullRequestDiffFileContentsResult.Type;
758
759const MAX_FILE_PATH_LENGTH = 4096;
760// Preserve filename whitespace so viewed marks match host paths.
761const FilePath = Schema.String.check(Schema.isNonEmpty(), Schema.isMaxLength(MAX_FILE_PATH_LENGTH));
762
763export const PullRequestFileViewedState = Schema.Literals(["unviewed", "viewed", "dismissed"]);
764export type PullRequestFileViewedState = typeof PullRequestFileViewedState.Type;
765
766export const PullRequestFileViewed = Schema.Struct({
767 path: FilePath,
768 state: PullRequestFileViewedState,
769});
770export type PullRequestFileViewed = typeof PullRequestFileViewed.Type;
771
772export const PullRequestFilesViewedResult = Schema.Struct({
773 /** Only the files the host reported a state for. A file missing from this list is unviewed. */
774 files: Schema.Array(PullRequestFileViewed),
775 truncated: Schema.Boolean,
776});
777export type PullRequestFilesViewedResult = typeof PullRequestFilesViewedResult.Type;
778
779const PullRequestLineCount = Schema.Struct({
780 additions: NonNegativeInt,
781 deletions: NonNegativeInt,
782});
783
784/**
785 * A change's line counts split by what the changed files are, judged from their paths. Null when
786 * the host gives no per-file counts, or has more files than one read covers: a split of part of
787 * the change would not add up to the totals shown beside it.
788 */
789export const PullRequestChangeBreakdown = Schema.NullOr(
790 Schema.Struct({
791 code: PullRequestLineCount,
792 tests: PullRequestLineCount,
793 mocks: PullRequestLineCount,
794 generated: PullRequestLineCount,
795 // Servers from before the docs split send no key; their docs lines sit in `code`.
796 docs: PullRequestLineCount.pipe(
797 Schema.withDecodingDefault(Effect.succeed({ additions: 0, deletions: 0 })),
798 ),
799 }),
800);
801export type PullRequestChangeBreakdown = typeof PullRequestChangeBreakdown.Type;
802
803const MAX_FILES_VIEWED_PRESSES = 500;
804
805export const PullRequestSetFilesViewedInput = Schema.Struct({
806 ...PullRequestRef.fields,
807 files: Schema.Array(
808 Schema.Struct({
809 path: FilePath,
810 viewed: Schema.Boolean,
811 /** The file's version in the diff the reader was shown; without it the head's is recorded. */
812 revision: Schema.optional(TrimmedNonEmptyString.check(Schema.isMaxLength(256))),
813 }),
814 ).check(Schema.isMaxLength(MAX_FILES_VIEWED_PRESSES)),
815});
816export type PullRequestSetFilesViewedInput = typeof PullRequestSetFilesViewedInput.Type;
817
818export const PullRequestStackHead = Schema.Struct({
819 number: PositiveInt,
820 headSha: TrimmedNonEmptyString,
821});
822export type PullRequestStackHead = typeof PullRequestStackHead.Type;
823
824export const PullRequestActionInput = Schema.Struct({
825 /** Native stack scope; only send to environments advertising pullRequestStackActions. */
826 stackNumber: Schema.optional(PositiveInt),
827 expectedStackHeads: Schema.optional(Schema.Array(PullRequestStackHead)),
828 ...PullRequestRef.fields,
829 action: PullRequestAction,
830 mergeMethod: Schema.optional(PullRequestMergeMethod),
831 updateMethod: Schema.optional(PullRequestUpdateMethod),
832 /** Opt-in, because older clients decode the action's success as void and reject a summary. */
833 replyWithSummary: Schema.optional(Schema.Literal(true)),
834});
835export type PullRequestActionInput = typeof PullRequestActionInput.Type;
836
837// Preserve whitespace because it affects Markdown formatting.
838const CommentBody = Schema.String.check(Schema.isNonEmpty()).check(Schema.isMaxLength(65_536));
839
840export const PullRequestCommentInput = Schema.Struct({
841 ...PullRequestRef.fields,
842 body: CommentBody,
843});
844export type PullRequestCommentInput = typeof PullRequestCommentInput.Type;
845
846export const PullRequestUpdateInput = Schema.Struct({
847 ...PullRequestRef.fields,
848 title: Schema.optional(TrimmedNonEmptyString.check(Schema.isMaxLength(1024))),
849 body: Schema.optional(Schema.String.check(Schema.isMaxLength(65_536))),
850 maintainerCanModify: Schema.optional(Schema.Boolean),
851});
852export type PullRequestUpdateInput = typeof PullRequestUpdateInput.Type;
853
854/** Comment kind selects the endpoint; GitHub uses separate mutations for conversation and line comments. */
855export const PullRequestCommentUpdateInput = Schema.Struct({
856 ...PullRequestRef.fields,
857 commentId: TrimmedNonEmptyString,
858 kind: Schema.Literals(["issue-comment", "review-comment"]),
859 body: CommentBody,
860});
861export type PullRequestCommentUpdateInput = typeof PullRequestCommentUpdateInput.Type;
862
863export const PullRequestReviewPosition = Schema.Union([
864 Schema.Struct({
865 kind: Schema.Literal("added"),
866 newLine: PositiveInt,
867 }),
868 Schema.Struct({
869 kind: Schema.Literal("deleted"),
870 oldLine: PositiveInt,
871 }),
872 Schema.Struct({
873 kind: Schema.Literal("context"),
874 oldLine: PositiveInt,
875 newLine: PositiveInt,
876 side: PullRequestDiffSide,
877 }),
878]);
879export type PullRequestReviewPosition = typeof PullRequestReviewPosition.Type;
880
881export const PullRequestReviewCommentDraft = Schema.Struct({
882 path: TrimmedNonEmptyString,
883 /** GitLab needs both names for renamed-file comments; hosts using one path ignore this. */
884 oldPath: Schema.optional(TrimmedNonEmptyString),
885 position: PullRequestReviewPosition,
886 /**
887 * The first line of a comment on a range, which ends at `position`. Sent only to a host whose
888 * capabilities include `review.rangeComment`.
889 */
890 startPosition: Schema.optional(PullRequestReviewPosition),
891 body: CommentBody,
892});
893export type PullRequestReviewCommentDraft = typeof PullRequestReviewCommentDraft.Type;
894
895export const PullRequestSubmitReviewInput = Schema.Struct({
896 ...PullRequestRef.fields,
897 verdict: PullRequestReviewVerdict,
898 body: Schema.String.check(Schema.isMaxLength(65_536)),
899 comments: Schema.Array(PullRequestReviewCommentDraft),
900});
901export type PullRequestSubmitReviewInput = typeof PullRequestSubmitReviewInput.Type;
902
903export const PullRequestThreadCommentsInput = Schema.Struct({
904 ...PullRequestRef.fields,
905 threadId: TrimmedNonEmptyString,
906 cursor: TrimmedNonEmptyString,
907});
908export type PullRequestThreadCommentsInput = typeof PullRequestThreadCommentsInput.Type;
909
910export const PullRequestThreadCommentsResult = Schema.Struct({
911 comments: Schema.Array(PullRequestThreadComment),
912 nextCursor: Schema.NullOr(TrimmedNonEmptyString),
913 // Comments the host hid that this page left out; the thread's `commentCount` still counts them.
914 hiddenCount: Schema.optional(NonNegativeInt),
915});
916export type PullRequestThreadCommentsResult = typeof PullRequestThreadCommentsResult.Type;
917
918export const PullRequestThreadReplyInput = Schema.Struct({
919 ...PullRequestRef.fields,
920 threadId: TrimmedNonEmptyString,
921 body: CommentBody,
922});
923export type PullRequestThreadReplyInput = typeof PullRequestThreadReplyInput.Type;
924
925export const PullRequestThreadResolutionInput = Schema.Struct({
926 ...PullRequestRef.fields,
927 threadId: TrimmedNonEmptyString,
928 resolved: Schema.Boolean,
929});
930export type PullRequestThreadResolutionInput = typeof PullRequestThreadResolutionInput.Type;
931
932export const PullRequestReactionInput = Schema.Struct({
933 ...PullRequestRef.fields,
934 subjectId: Schema.optional(TrimmedNonEmptyString),
935 content: PullRequestReactionContent,
936 reacted: Schema.Boolean,
937});
938export type PullRequestReactionInput = typeof PullRequestReactionInput.Type;
939
940export const PullRequestReviewerRequestInput = Schema.Struct({
941 ...PullRequestRef.fields,
942 reviewers: Schema.Array(
943 Schema.Struct({ id: TrimmedNonEmptyString, kind: PullRequestReviewerKind }),
944 ).check(Schema.isMinLength(1), Schema.isMaxLength(25)),
945 requested: Schema.Boolean,
946});
947export type PullRequestReviewerRequestInput = typeof PullRequestReviewerRequestInput.Type;
948
949export const PullRequestLabelChangeInput = Schema.Struct({
950 ...PullRequestRef.fields,
951 labels: Schema.Array(TrimmedNonEmptyString).check(Schema.isMinLength(1), Schema.isMaxLength(25)),
952 applied: Schema.Boolean,
953});
954export type PullRequestLabelChangeInput = typeof PullRequestLabelChangeInput.Type;
955
956/**
957 * The names keep their `cli-` prefix for wire compatibility; for a host read with a credential
958 * rather than a tool they mean "no credential" and "a refused credential".
959 */
960export const PullRequestUnavailableReason = Schema.Literals([
961 "cli-missing",
962 "cli-unauthenticated",
963 "provider-unsupported",
964]);
965export type PullRequestUnavailableReason = typeof PullRequestUnavailableReason.Type;
966
967/**
968 * `author:me` names whoever is signed in to the host being read, GitHub's `@me` spelled either
969 * way. A host's own search would answer it, but the page and the server both re-check an author
970 * against the row's login, so the name is resolved before either comparison rather than being
971 * matched as the literal login "me".
972 */
973export function resolvePullRequestAuthorFilter(
974 author: string,
975 viewer: string | null | undefined,
976): string {
977 const trimmed = author.trim();
978 if (!/^@?me$/i.test(trimmed)) return trimmed;
979 return viewer === null || viewer === undefined || viewer.trim().length === 0 ? trimmed : viewer;
980}
981
982export class PullRequestUnavailableError extends Schema.TaggedError<PullRequestUnavailableError>()(
983 "PullRequestUnavailableError",
984 {
985 reason: PullRequestUnavailableReason,
986 provider: Schema.optional(SourceControlProviderKind),
987 listResult: Schema.optional(PullRequestListResult),
988 /**
989 * What the host needs on the server, in its own words. Absent from older servers, which
990 * shipped no such field, and for a host that names nothing.
991 */
992 requirement: Schema.optional(TrimmedNonEmptyString),
993 cause: Schema.optional(Schema.Defect()),
994 },
995 { httpApiStatus: 503 },
996) {
997 [HttpServerRespondable.symbol]() {
998 return HttpServerResponse.schemaJson(PullRequestUnavailableError)(this, { status: 503 });
999 }
1000
1001 override get message(): string {
1002 switch (this.reason) {
1003 case "cli-missing":
1004 return this.requirement ?? "The tool this host is read through is not installed or set up.";
1005 case "cli-unauthenticated":
1006 return this.requirement ?? "This host has no working credentials.";
1007 case "provider-unsupported":
1008 return "Change requests cannot be browsed for this project's host yet.";
1009 }
1010 }
1011}
1012
1013export class PullRequestOperationError extends Schema.TaggedError<PullRequestOperationError>()(
1014 "PullRequestOperationError",
1015 {
1016 operation: Schema.String,
1017 detail: TrimmedNonEmptyString,
1018 reason: Schema.optional(Schema.Literal("not-found")),
1019 listResult: Schema.optional(PullRequestListResult),
1020 cause: Schema.optional(Schema.Defect()),
1021 },
1022 { httpApiStatus: 502 },
1023) {
1024 [HttpServerRespondable.symbol]() {
1025 return HttpServerResponse.schemaJson(PullRequestOperationError)(this, { status: 502 });
1026 }
1027
1028 override get message(): string {
1029 return `Pull request operation ${this.operation} failed: ${this.detail}`;
1030 }
1031}