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