The best way to control Claude Code, Codex and more from any computer or phone

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