dex-connector-github 0.1.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,861 @@
1
+ # Copyright (c) 2026 Super Durable
2
+ # SPDX-License-Identifier: MIT
3
+ """GitHub Query invocation, validation, and provider response mapping."""
4
+
5
+ import json
6
+ import re
7
+ import unicodedata
8
+ from dataclasses import replace
9
+ from datetime import UTC, datetime, timedelta
10
+ from typing import Any, cast
11
+ from urllib.parse import parse_qs, quote, urlsplit, urlunsplit
12
+
13
+ from dex_connectors.sdk import Call, FailureKind, QueryAttempt
14
+
15
+ from ._generated import definitions as definitions
16
+ from .client import _LOGIN, _REPOSITORY, Client, _decode, _path_escape, _Response
17
+ from .models import (
18
+ AuthenticatedProfile,
19
+ CommitPage,
20
+ CommitSummary,
21
+ GetAuthenticatedProfileInput,
22
+ ListCommitsInput,
23
+ ListMergedPullRequestsInput,
24
+ ListPublicRepositoriesInput,
25
+ ListPullRequestFilesInput,
26
+ ListReleasesInput,
27
+ MergedPullRequest,
28
+ MergedPullRequestPage,
29
+ PublicRepositories,
30
+ PullRequestFile,
31
+ PullRequestFilePage,
32
+ Release,
33
+ ReleasePage,
34
+ Repository,
35
+ )
36
+
37
+
38
+ def _string(value: Any, maximum: int = 0) -> str:
39
+ if value is None:
40
+ return ""
41
+ if not isinstance(value, str):
42
+ raise ValueError("GitHub response string type differs")
43
+ value = value.strip()
44
+ if maximum:
45
+ value = value.encode("utf-8")[:maximum].decode("utf-8", errors="ignore")
46
+ return cast(str, value)
47
+
48
+
49
+ def _raw_string(value: Any) -> str:
50
+ if value is None:
51
+ return ""
52
+ if not isinstance(value, str):
53
+ raise ValueError("GitHub response string type differs")
54
+ return value
55
+
56
+
57
+ def _integer(value: Any) -> int:
58
+ if value is None:
59
+ return 0
60
+ if type(value) is not int:
61
+ raise ValueError("GitHub response integer type differs")
62
+ if not -(1 << 63) <= value < (1 << 63):
63
+ raise ValueError("GitHub response integer exceeds Go int64")
64
+ return value
65
+
66
+
67
+ def _boolean(value: Any) -> bool:
68
+ if value is None:
69
+ return False
70
+ if type(value) is not bool:
71
+ raise ValueError("GitHub response boolean type differs")
72
+ return value
73
+
74
+
75
+ def _time(value: Any, required: bool = False) -> datetime | None:
76
+ if value is None:
77
+ if required:
78
+ raise ValueError("GitHub response time is absent")
79
+ return None
80
+ if not isinstance(value, str):
81
+ raise ValueError("GitHub response time type differs")
82
+ match = re.fullmatch(
83
+ r"(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2}):(\d{2})(?:[.,](\d+))?(Z|[+-]\d{2}:\d{2})",
84
+ value,
85
+ )
86
+ if match is None:
87
+ raise ValueError("GitHub response time is invalid")
88
+ year, month, day, hour, minute, second = (int(match.group(index)) for index in range(1, 7))
89
+ raw_fraction = match.group(7) or ""
90
+ if len(raw_fraction) > 6 and raw_fraction[6:].strip("0"):
91
+ raise ValueError("GitHub response time cannot be represented exactly as datetime")
92
+ fraction = raw_fraction[:6].ljust(6, "0")
93
+ zone = match.group(8)
94
+ try:
95
+ parsed = datetime(year, month, day, hour, minute, second, int(fraction), tzinfo=UTC)
96
+ if zone != "Z":
97
+ zone_hours, zone_minutes = int(zone[1:3]), int(zone[4:6])
98
+ if zone_hours > 99 or zone_minutes > 59:
99
+ raise ValueError("GitHub response zone is invalid")
100
+ offset = timedelta(hours=zone_hours, minutes=zone_minutes)
101
+ parsed -= offset if zone[0] == "+" else -offset
102
+ return parsed
103
+ except (ValueError, OverflowError) as error:
104
+ raise ValueError("GitHub response time is invalid") from error
105
+
106
+
107
+ def _url(value: Any) -> str:
108
+ candidate = _string(value, 2048)
109
+ if re.search(r"%(?![0-9A-Fa-f]{2})", candidate):
110
+ return ""
111
+ try:
112
+ parsed = urlsplit(candidate)
113
+ if parsed.scheme not in ("http", "https") or not parsed.hostname:
114
+ return ""
115
+ except ValueError:
116
+ return ""
117
+ path = quote(parsed.path, safe="/!$&'()*+,;=:@[]-._~%")
118
+ fragment = quote(parsed.fragment, safe="!$&()*+,;=:@/?-._~%")
119
+ result = urlunsplit((parsed.scheme, parsed.netloc, path, parsed.query, fragment))
120
+ if not parsed.query and candidate.split("#", 1)[0].endswith("?"):
121
+ position = result.find("#")
122
+ result = result + "?" if position < 0 else result[:position] + "?" + result[position:]
123
+ return result
124
+
125
+
126
+ def _truncate(value: Any, maximum: int) -> tuple[str, bool]:
127
+ if value is None:
128
+ return "", False
129
+ if not isinstance(value, str):
130
+ raise ValueError("GitHub text type differs")
131
+ return value[:maximum], len(value) > maximum
132
+
133
+
134
+ def _is_go_mail_address(value: str) -> bool:
135
+ if not value or len(value) > 320 or any(character in value for character in "<>\r\n()"):
136
+ return False
137
+ if value.startswith('"'):
138
+ closing_quote = value.find('"', 1)
139
+ if closing_quote < 2 or value[closing_quote + 1 : closing_quote + 2] != "@":
140
+ return False
141
+ local = value[: closing_quote + 1]
142
+ domain = value[closing_quote + 2 :]
143
+ if any(ord(character) < 32 or ord(character) == 127 for character in local[1:-1]):
144
+ return False
145
+ else:
146
+ local, separator, domain = value.rpartition("@")
147
+ if not separator or not local or any(not segment for segment in local.split(".")):
148
+ return False
149
+ atom_special = "!#$%&'*+-/=?^_`{|}~"
150
+ if any(
151
+ not (
152
+ character.isalnum()
153
+ or character in atom_special
154
+ or character == "."
155
+ or (ord(character) > 127 and not character.isspace())
156
+ )
157
+ for character in local
158
+ ):
159
+ return False
160
+ if domain.startswith("[") and domain.endswith("]"):
161
+ return bool(domain[1:-1]) and all(
162
+ 32 < ord(character) < 127 and character != "]" for character in domain[1:-1]
163
+ )
164
+ if not domain or any(not segment for segment in domain.split(".")):
165
+ return False
166
+ return all(
167
+ character.isalnum() or character == "-" or (ord(character) > 127 and not character.isspace())
168
+ for character in domain
169
+ if character != "."
170
+ )
171
+
172
+
173
+ def _validate_repository_payload(item: Any) -> None:
174
+ if not isinstance(item, dict):
175
+ raise ValueError("repository object differs")
176
+ for name in ("id", "stargazers_count", "forks_count", "open_issues_count"):
177
+ _integer(item.get(name))
178
+ for name in ("private", "fork", "archived", "disabled"):
179
+ _boolean(item.get(name))
180
+ for name in ("name", "full_name", "visibility", "html_url", "description", "homepage", "language"):
181
+ _string(item.get(name))
182
+ for name in ("created_at", "updated_at", "pushed_at"):
183
+ _time(item.get(name))
184
+ topics = item.get("topics") or []
185
+ if not isinstance(topics, list):
186
+ raise ValueError("repository topics differ")
187
+ for topic in topics:
188
+ _string(topic)
189
+
190
+
191
+ def _page(response: _Response, current: int) -> int:
192
+ for match in re.finditer(r'<([^>]*)>\s*;\s*rel="([^"]*)"', response.headers.get("Link", "")):
193
+ if "next" not in match.group(2).lower().split():
194
+ continue
195
+ values = parse_qs(urlsplit(match.group(1)).query)
196
+ try:
197
+ number = int(values.get("page", [""])[0])
198
+ except ValueError as error:
199
+ raise ValueError("GitHub pagination link is invalid") from error
200
+ if number <= current:
201
+ raise ValueError("GitHub pagination link does not advance")
202
+ return number
203
+ return 0
204
+
205
+
206
+ def _window(start: datetime, end: datetime) -> bool:
207
+ return (
208
+ isinstance(start, datetime)
209
+ and isinstance(end, datetime)
210
+ and start.year != 1
211
+ and end.year != 1
212
+ and start < end
213
+ )
214
+
215
+
216
+ def _provider_time(value: datetime) -> str:
217
+ return value.astimezone(UTC).strftime("%Y-%m-%dT%H:%M:%SZ")
218
+
219
+
220
+ def _repository_input(
221
+ client: Client, operation: str, value: Any, empty: Any
222
+ ) -> tuple[str, str, QueryAttempt[Any] | None]:
223
+ owner = value.owner.strip()
224
+ repository = value.repository.strip()
225
+ if not _LOGIN.fullmatch(owner):
226
+ return (
227
+ "",
228
+ "",
229
+ client._branch(
230
+ operation, "defect", empty, FailureKind.VALIDATION, "GitHub repository owner is invalid"
231
+ ),
232
+ )
233
+ if not _REPOSITORY.fullmatch(repository) or repository in (".", ".."):
234
+ return (
235
+ "",
236
+ "",
237
+ client._branch(
238
+ operation, "defect", empty, FailureKind.VALIDATION, "GitHub repository name is invalid"
239
+ ),
240
+ )
241
+ return owner, repository, None
242
+
243
+
244
+ def _page_input(
245
+ client: Client, operation: str, value: Any, empty: Any, default: int
246
+ ) -> tuple[int, int, QueryAttempt[Any] | None]:
247
+ size, page = value.page_size or default, value.page or 1
248
+ if not (1 <= size <= 100 and page >= 1):
249
+ return (
250
+ 0,
251
+ 0,
252
+ client._branch(
253
+ operation,
254
+ "defect",
255
+ empty,
256
+ FailureKind.VALIDATION,
257
+ "page size must be 1 through 100 and page must be positive",
258
+ ),
259
+ )
260
+ return size, page, None
261
+
262
+
263
+ class _Operation:
264
+ definition_value: Any
265
+ operation_id: str
266
+ empty: Any
267
+ success_branch: str
268
+
269
+ def __init__(self, client: Client) -> None:
270
+ self.client = client
271
+
272
+ def definition(self) -> Any:
273
+ """Return the generated immutable operation definition."""
274
+ return self.definition_value
275
+
276
+ async def _credential(self, call: Call) -> tuple[Any, QueryAttempt[Any] | None]:
277
+ return await self.client._credential(call, self.operation_id, self.empty)
278
+
279
+ async def _fetch(
280
+ self, call: Call, credential: Any, path: str, query: dict[str, str] | None = None
281
+ ) -> tuple[_Response | None, QueryAttempt[Any] | None]:
282
+ return await self.client._request(
283
+ call,
284
+ self.operation_id,
285
+ credential,
286
+ path,
287
+ query or {},
288
+ self.empty,
289
+ "GitHub response exceeds the configured size limit",
290
+ )
291
+
292
+ def _invalid(self, response: _Response, message: str) -> QueryAttempt[Any]:
293
+ return self.client._branch(
294
+ self.operation_id,
295
+ "invalidResponse",
296
+ self.empty,
297
+ FailureKind.PROTOCOL,
298
+ message,
299
+ response.receipt(),
300
+ )
301
+
302
+ def _success(
303
+ self, value: Any, response: _Response, metadata: dict[str, str] | None = None
304
+ ) -> QueryAttempt[Any]:
305
+ return QueryAttempt.branch_result(self.success_branch, value, response.receipt(metadata))
306
+
307
+
308
+ class GetAuthenticatedProfileOperation(_Operation):
309
+ """Read the account and verified primary email."""
310
+
311
+ operation_id = "getAuthenticatedProfile"
312
+ definition_value = definitions.GET_AUTHENTICATED_PROFILE_DEFINITION
313
+ success_branch = "profileLoaded"
314
+ empty = AuthenticatedProfile()
315
+
316
+ async def invoke(
317
+ self, call: Call, input: GetAuthenticatedProfileInput
318
+ ) -> QueryAttempt[AuthenticatedProfile]:
319
+ """Read both profile and email endpoints in one Query attempt."""
320
+ credential, early = await self._credential(call)
321
+ if early:
322
+ return early
323
+ profile_response, early = await self._fetch(call, credential, "/user")
324
+ if early:
325
+ return early
326
+ assert profile_response is not None
327
+ try:
328
+ profile = _decode(profile_response.body, dict)
329
+ if _integer(profile.get("id")) <= 0 or not _string(profile.get("login")):
330
+ raise ValueError("invalid profile")
331
+ value = AuthenticatedProfile(
332
+ subject=str(profile["id"]),
333
+ login=_string(profile["login"], 100),
334
+ name=_string(profile.get("name"), 256),
335
+ verified_email="",
336
+ avatar_url=_url(profile.get("avatar_url")),
337
+ profile_url=_url(profile.get("html_url")),
338
+ company=_string(profile.get("company"), 256),
339
+ blog_url=_url(profile.get("blog")),
340
+ location=_string(profile.get("location"), 256),
341
+ bio=_string(profile.get("bio"), 1024),
342
+ twitter_username=_string(profile.get("twitter_username"), 100),
343
+ public_repos=max(0, _integer(profile.get("public_repos"))),
344
+ followers=max(0, _integer(profile.get("followers"))),
345
+ following=max(0, _integer(profile.get("following"))),
346
+ created_at=_time(profile.get("created_at")),
347
+ updated_at=_time(profile.get("updated_at")),
348
+ )
349
+ except (ValueError, json.JSONDecodeError):
350
+ return self._invalid(profile_response, "GitHub returned an invalid profile response")
351
+ email_response, early = await self._fetch(call, credential, "/user/emails", {"per_page": "100"})
352
+ if early:
353
+ if early.kind == "branch" and early.receipt is not None and email_response is not None:
354
+ early.receipt.metadata.update(
355
+ {
356
+ "profileRequestId": profile_response.request_id,
357
+ "emailRequestId": email_response.request_id,
358
+ }
359
+ )
360
+ return early
361
+ assert email_response is not None
362
+ metadata = {
363
+ "profileRequestId": profile_response.request_id,
364
+ "emailRequestId": email_response.request_id,
365
+ }
366
+ try:
367
+ emails = _decode(email_response.body, list)
368
+ verified = ""
369
+ for candidate in emails:
370
+ if not isinstance(candidate, dict):
371
+ raise ValueError("invalid email")
372
+ email = _string(candidate.get("email")).lower()
373
+ is_primary = _boolean(candidate.get("primary"))
374
+ is_verified = _boolean(candidate.get("verified"))
375
+ if is_primary and is_verified:
376
+ if _is_go_mail_address(email):
377
+ verified = email
378
+ break
379
+ except (ValueError, json.JSONDecodeError):
380
+ return self.client._branch(
381
+ self.operation_id,
382
+ "invalidResponse",
383
+ self.empty,
384
+ FailureKind.PROTOCOL,
385
+ "GitHub returned an invalid email response",
386
+ email_response.receipt(metadata),
387
+ )
388
+ if not verified:
389
+ return self.client._branch(
390
+ self.operation_id,
391
+ "verifiedEmailRequired",
392
+ self.empty,
393
+ FailureKind.AUTHENTICATION,
394
+ "GitHub primary verified email is required",
395
+ email_response.receipt(metadata),
396
+ )
397
+ return self._success(replace(value, verified_email=verified), email_response, metadata)
398
+
399
+
400
+ class ListPublicRepositoriesOperation(_Operation):
401
+ """List bounded public repositories for one login."""
402
+
403
+ operation_id = "listPublicRepositories"
404
+ definition_value = definitions.LIST_PUBLIC_REPOSITORIES_DEFINITION
405
+ success_branch = "repositoriesLoaded"
406
+ empty = PublicRepositories()
407
+
408
+ async def invoke(
409
+ self, call: Call, input: ListPublicRepositoriesInput
410
+ ) -> QueryAttempt[PublicRepositories]:
411
+ """Follow GitHub pages until the configured result limit is reached."""
412
+ login = input.login.strip()
413
+ if not _LOGIN.fullmatch(login):
414
+ return self.client._branch(
415
+ self.operation_id, "defect", self.empty, FailureKind.VALIDATION, "GitHub login is invalid"
416
+ )
417
+ limit = input.limit or self.client.config.default_repository_limit
418
+ if limit < 1 or limit > self.client.config.max_repositories:
419
+ return self.client._branch(
420
+ self.operation_id,
421
+ "defect",
422
+ self.empty,
423
+ FailureKind.VALIDATION,
424
+ "repository limit is outside the configured range",
425
+ )
426
+ credential, early = await self._credential(call)
427
+ if early:
428
+ return early
429
+ repositories: dict[int, Repository] = {}
430
+ page = 1
431
+ truncated = False
432
+ while True:
433
+ response, early = await self._fetch(
434
+ call,
435
+ credential,
436
+ "/users/" + _path_escape(login) + "/repos",
437
+ {
438
+ "type": "owner",
439
+ "sort": "pushed",
440
+ "direction": "desc",
441
+ "per_page": "100",
442
+ "page": str(page),
443
+ },
444
+ )
445
+ if early:
446
+ if early.kind == "branch" and early.receipt is not None and response is not None:
447
+ early.receipt.metadata["pagesRead"] = str(page)
448
+ return early
449
+ assert response is not None
450
+ try:
451
+ values = _decode(response.body, list)
452
+ for item in values:
453
+ _validate_repository_payload(item)
454
+ for item in values:
455
+ identifier = _integer(item.get("id"))
456
+ if (
457
+ identifier <= 0
458
+ or _boolean(item.get("private"))
459
+ or _string(item.get("visibility")) not in ("", "public")
460
+ or identifier in repositories
461
+ ):
462
+ continue
463
+ if len(repositories) == limit:
464
+ truncated = True
465
+ break
466
+ topics = item.get("topics") or []
467
+ if not isinstance(topics, list):
468
+ raise ValueError("repository topics differ")
469
+ repositories[identifier] = Repository(
470
+ id=identifier,
471
+ name=_string(item.get("name"), 256),
472
+ full_name=_string(item.get("full_name"), 512),
473
+ description=_string(item.get("description"), 1024),
474
+ profile_url=_url(item.get("html_url")),
475
+ homepage_url=_url(item.get("homepage")),
476
+ language=_string(item.get("language"), 128),
477
+ topics=tuple(
478
+ value for value in (_string(topic, 64) for topic in topics[:100]) if value
479
+ ),
480
+ fork=_boolean(item.get("fork")),
481
+ archived=_boolean(item.get("archived")),
482
+ disabled=_boolean(item.get("disabled")),
483
+ stargazers_count=max(0, _integer(item.get("stargazers_count"))),
484
+ forks_count=max(0, _integer(item.get("forks_count"))),
485
+ open_issues_count=max(0, _integer(item.get("open_issues_count"))),
486
+ created_at=_time(item.get("created_at")),
487
+ updated_at=_time(item.get("updated_at")),
488
+ pushed_at=_time(item.get("pushed_at")),
489
+ )
490
+ except (ValueError, json.JSONDecodeError):
491
+ return self.client._branch(
492
+ self.operation_id,
493
+ "invalidResponse",
494
+ self.empty,
495
+ FailureKind.PROTOCOL,
496
+ "GitHub returned an invalid repository response",
497
+ response.receipt({"pagesRead": str(page)}),
498
+ )
499
+ has_next = 'rel="next"' in response.headers.get("Link", "")
500
+ if len(repositories) == limit:
501
+ truncated = truncated or has_next
502
+ break
503
+ if not has_next or not values:
504
+ break
505
+ page += 1
506
+ ordered = sorted(
507
+ repositories.values(),
508
+ key=lambda value: (
509
+ value.pushed_at is None,
510
+ -(value.pushed_at.timestamp() if value.pushed_at else 0),
511
+ value.id,
512
+ ),
513
+ )
514
+ return self._success(
515
+ PublicRepositories(tuple(ordered), truncated), response, {"pagesRead": str(page)}
516
+ )
517
+
518
+
519
+ class _RepositoryPageOperation(_Operation):
520
+ default_page_size = 30
521
+
522
+ def _validate(self, input: Any) -> tuple[str, str, int, int, QueryAttempt[Any] | None]:
523
+ owner, repository, early = _repository_input(self.client, self.operation_id, input, self.empty)
524
+ if early:
525
+ return owner, repository, 0, 0, early
526
+ size, page, early = _page_input(
527
+ self.client, self.operation_id, input, self.empty, self.default_page_size
528
+ )
529
+ return owner, repository, size, page, early
530
+
531
+ async def _repository_fetch(
532
+ self, call: Call, credential: Any, owner: str, repository: str, suffix: str, query: dict[str, str]
533
+ ) -> tuple[_Response | None, QueryAttempt[Any] | None]:
534
+ return await self._fetch(
535
+ call, credential, "/repos/" + _path_escape(owner) + "/" + _path_escape(repository) + suffix, query
536
+ )
537
+
538
+
539
+ class ListMergedPullRequestsOperation(_RepositoryPageOperation):
540
+ """Read one page of merged pull requests."""
541
+
542
+ operation_id = "listMergedPullRequests"
543
+ definition_value = definitions.LIST_MERGED_PULL_REQUESTS_DEFINITION
544
+ success_branch = "listed"
545
+ empty = MergedPullRequestPage()
546
+
547
+ async def invoke(
548
+ self, call: Call, input: ListMergedPullRequestsInput
549
+ ) -> QueryAttempt[MergedPullRequestPage]:
550
+ """Search merged pull requests in a bounded time window."""
551
+ owner, repository, size, page, early = self._validate(input)
552
+ if early:
553
+ return early
554
+ if not _window(input.merged_after, input.merged_before):
555
+ return self.client._branch(
556
+ self.operation_id,
557
+ "defect",
558
+ self.empty,
559
+ FailureKind.VALIDATION,
560
+ "merged pull request window must have a start before its end",
561
+ )
562
+ if page > 1000 or (page - 1) * size >= 1000:
563
+ return self.client._branch(
564
+ self.operation_id,
565
+ "defect",
566
+ self.empty,
567
+ FailureKind.VALIDATION,
568
+ "search page starts after GitHub's first 1000 results",
569
+ )
570
+ credential, early = await self._credential(call)
571
+ if early:
572
+ return early
573
+ search = (
574
+ f"repo:{owner}/{repository} is:pr is:merged "
575
+ f"merged:{_provider_time(input.merged_after)}..{_provider_time(input.merged_before)}"
576
+ )
577
+ response, early = await self._fetch(
578
+ call,
579
+ credential,
580
+ "/search/issues",
581
+ {"q": search, "sort": "created", "order": "desc", "per_page": str(size), "page": str(page)},
582
+ )
583
+ if early:
584
+ return early
585
+ assert response is not None
586
+ try:
587
+ data = _decode(response.body, dict)
588
+ if data.get("total_count") is None or not isinstance(data.get("items"), list):
589
+ raise ValueError("invalid search")
590
+ items = []
591
+ for item in data["items"]:
592
+ request = item.get("pull_request")
593
+ if (
594
+ _integer(item.get("number")) <= 0
595
+ or not isinstance(request, dict)
596
+ or request.get("merged_at") is None
597
+ ):
598
+ raise ValueError("invalid merged pull request")
599
+ body, truncated = _truncate(
600
+ item.get("body"), self.client.config.max_pull_request_body_characters
601
+ )
602
+ labels = item.get("labels") or []
603
+ author = item.get("user") or {}
604
+ if not isinstance(labels, list) or not isinstance(author, dict):
605
+ raise ValueError("invalid labels or author")
606
+ items.append(
607
+ MergedPullRequest(
608
+ number=_integer(item["number"]),
609
+ title=_string(item.get("title"), 1024),
610
+ body=body,
611
+ body_truncated=truncated,
612
+ url=_url(item.get("html_url")),
613
+ author_login=_string(author.get("login"), 100),
614
+ merged_at=cast(datetime, _time(request["merged_at"], True)),
615
+ labels=tuple(
616
+ value
617
+ for value in (_string(label.get("name"), 256) for label in labels[:100])
618
+ if value
619
+ ),
620
+ )
621
+ )
622
+ next_page = _page(response, page)
623
+ return self._success(
624
+ MergedPullRequestPage(
625
+ tuple(items),
626
+ max(0, _integer(data["total_count"])),
627
+ _boolean(data.get("incomplete_results")),
628
+ next_page,
629
+ ),
630
+ response,
631
+ )
632
+ except (ValueError, json.JSONDecodeError, AttributeError):
633
+ return self._invalid(response, "GitHub returned an invalid search response")
634
+
635
+
636
+ class ListPullRequestFilesOperation(_RepositoryPageOperation):
637
+ """Read one page of changed files for a pull request."""
638
+
639
+ operation_id = "listPullRequestFiles"
640
+ definition_value = definitions.LIST_PULL_REQUEST_FILES_DEFINITION
641
+ success_branch = "listed"
642
+ empty = PullRequestFilePage()
643
+ default_page_size = 50
644
+
645
+ async def invoke(self, call: Call, input: ListPullRequestFilesInput) -> QueryAttempt[PullRequestFilePage]:
646
+ """Read changed file metadata with bounded patch text."""
647
+ owner, repository, size, page, early = self._validate(input)
648
+ if early:
649
+ return early
650
+ if input.number <= 0:
651
+ return self.client._branch(
652
+ self.operation_id,
653
+ "defect",
654
+ self.empty,
655
+ FailureKind.VALIDATION,
656
+ "pull request number must be positive",
657
+ )
658
+ credential, early = await self._credential(call)
659
+ if early:
660
+ return early
661
+ response, early = await self._repository_fetch(
662
+ call,
663
+ credential,
664
+ owner,
665
+ repository,
666
+ f"/pulls/{input.number}/files",
667
+ {"per_page": str(size), "page": str(page)},
668
+ )
669
+ if early:
670
+ return early
671
+ assert response is not None
672
+ try:
673
+ data = _decode(response.body, list)
674
+ files = []
675
+ for item in data:
676
+ filename = _raw_string(item.get("filename"))
677
+ previous = _raw_string(item.get("previous_filename"))
678
+ status = _string(item.get("status"), 32)
679
+ if (
680
+ not filename
681
+ or len(filename.encode()) > 4096
682
+ or "\0" in filename
683
+ or (previous and (len(previous.encode()) > 4096 or "\0" in previous))
684
+ or not status
685
+ ):
686
+ raise ValueError("invalid file")
687
+ patch, truncated = _truncate(item.get("patch"), self.client.config.max_patch_characters)
688
+ files.append(
689
+ PullRequestFile(
690
+ filename=filename,
691
+ previous_filename=previous,
692
+ status=status,
693
+ additions=max(0, _integer(item.get("additions"))),
694
+ deletions=max(0, _integer(item.get("deletions"))),
695
+ changes=max(0, _integer(item.get("changes"))),
696
+ patch=patch,
697
+ patch_truncated=truncated,
698
+ )
699
+ )
700
+ return self._success(PullRequestFilePage(tuple(files), _page(response, page)), response)
701
+ except (ValueError, json.JSONDecodeError, AttributeError):
702
+ return self._invalid(response, "GitHub returned an invalid changed-file response")
703
+
704
+
705
+ class ListReleasesOperation(_RepositoryPageOperation):
706
+ """Read one page of repository releases."""
707
+
708
+ operation_id = "listReleases"
709
+ definition_value = definitions.LIST_RELEASES_DEFINITION
710
+ success_branch = "listed"
711
+ empty = ReleasePage()
712
+
713
+ async def invoke(self, call: Call, input: ListReleasesInput) -> QueryAttempt[ReleasePage]:
714
+ """Read releases with bounded body text."""
715
+ owner, repository, size, page, early = self._validate(input)
716
+ if early:
717
+ return early
718
+ maximum = input.max_body_characters or 4000
719
+ if not 1 <= maximum <= 16384:
720
+ return self.client._branch(
721
+ self.operation_id,
722
+ "defect",
723
+ self.empty,
724
+ FailureKind.VALIDATION,
725
+ "maxBodyCharacters must be between 1 and 16384",
726
+ )
727
+ credential, early = await self._credential(call)
728
+ if early:
729
+ return early
730
+ response, early = await self._repository_fetch(
731
+ call, credential, owner, repository, "/releases", {"per_page": str(size), "page": str(page)}
732
+ )
733
+ if early:
734
+ return early
735
+ assert response is not None
736
+ try:
737
+ data = _decode(response.body, list)
738
+ if len(data) > size:
739
+ raise ValueError("release page is too large")
740
+ releases = []
741
+ for item in data:
742
+ created = _time(item.get("created_at"), True)
743
+ published = _time(item.get("published_at"))
744
+ draft = _boolean(item.get("draft"))
745
+ tag = _raw_string(item.get("tag_name"))
746
+ if (
747
+ _integer(item.get("id")) <= 0
748
+ or not tag
749
+ or len(tag.encode()) > 255
750
+ or any(
751
+ character.isspace() or unicodedata.category(character) == "Cc"
752
+ for character in tag
753
+ )
754
+ or (not draft and published is None)
755
+ ):
756
+ raise ValueError("invalid release")
757
+ body, truncated = _truncate(item.get("body"), maximum)
758
+ releases.append(
759
+ Release(
760
+ id=_integer(item["id"]),
761
+ tag_name=tag,
762
+ name=_string(item.get("name"), 1024),
763
+ url=_url(item.get("html_url")),
764
+ body=body,
765
+ body_truncated=truncated,
766
+ is_draft=draft,
767
+ is_prerelease=_boolean(item.get("prerelease")),
768
+ created_at=cast(datetime, created),
769
+ published_at=published,
770
+ )
771
+ )
772
+ return self._success(ReleasePage(tuple(releases), _page(response, page)), response)
773
+ except (ValueError, json.JSONDecodeError, AttributeError):
774
+ return self._invalid(response, "GitHub returned an invalid release page")
775
+
776
+
777
+ class ListCommitsOperation(_RepositoryPageOperation):
778
+ """Read one page of repository commits."""
779
+
780
+ operation_id = "listCommits"
781
+ definition_value = definitions.LIST_COMMITS_DEFINITION
782
+ success_branch = "listed"
783
+ empty = CommitPage()
784
+
785
+ async def invoke(self, call: Call, input: ListCommitsInput) -> QueryAttempt[CommitPage]:
786
+ """Read commits in a bounded window and classify empty repositories."""
787
+ owner, repository, size, page, early = self._validate(input)
788
+ if early:
789
+ return early
790
+ if not _window(input.since, input.until):
791
+ return self.client._branch(
792
+ self.operation_id,
793
+ "defect",
794
+ self.empty,
795
+ FailureKind.VALIDATION,
796
+ "commit window must have a start before its end",
797
+ )
798
+ for field, value, limit, spaces in (("path", input.path, 4096, True), ("ref", input.ref, 255, False)):
799
+ if len(value.encode()) > limit or any(
800
+ unicodedata.category(character) == "Cc" or (not spaces and character.isspace())
801
+ for character in value
802
+ ):
803
+ return self.client._branch(
804
+ self.operation_id,
805
+ "defect",
806
+ self.empty,
807
+ FailureKind.VALIDATION,
808
+ f"commit {field} is invalid",
809
+ )
810
+ credential, early = await self._credential(call)
811
+ if early:
812
+ return early
813
+ query = {
814
+ "since": _provider_time(input.since),
815
+ "until": _provider_time(input.until),
816
+ "per_page": str(size),
817
+ "page": str(page),
818
+ }
819
+ if input.path:
820
+ query["path"] = input.path
821
+ if input.ref:
822
+ query["sha"] = input.ref
823
+ response, early = await self._repository_fetch(call, credential, owner, repository, "/commits", query)
824
+ if early:
825
+ return early
826
+ assert response is not None
827
+ if response.status == 409:
828
+ return self._success(CommitPage(), response, {"repositoryEmpty": "true"})
829
+ try:
830
+ data = _decode(response.body, list)
831
+ commits = []
832
+ for item in data:
833
+ sha = _raw_string(item.get("sha"))
834
+ commit = item.get("commit") or {}
835
+ author = commit.get("author") or {}
836
+ committer = commit.get("committer") or {}
837
+ user = item.get("author") or {}
838
+ if (
839
+ not re.fullmatch(r"(?:[0-9a-f]{40}|[0-9a-f]{64})", sha)
840
+ or not author.get("date")
841
+ or not committer.get("date")
842
+ ):
843
+ raise ValueError("invalid commit")
844
+ message, truncated = _truncate(
845
+ commit.get("message"), self.client.config.max_commit_message_characters
846
+ )
847
+ commits.append(
848
+ CommitSummary(
849
+ sha=sha,
850
+ message=message,
851
+ message_truncated=truncated,
852
+ author_login=_string(user.get("login"), 100),
853
+ author_name=_string(author.get("name"), 256),
854
+ authored_at=cast(datetime, _time(author["date"], True)),
855
+ committed_at=cast(datetime, _time(committer["date"], True)),
856
+ url=_url(item.get("html_url")),
857
+ )
858
+ )
859
+ return self._success(CommitPage(tuple(commits), _page(response, page)), response)
860
+ except (ValueError, json.JSONDecodeError, AttributeError):
861
+ return self._invalid(response, "GitHub returned an invalid commit response")