Skip to main content

interprex_github/
code_reviews.rs

1//! Code-review operations implemented with GitHub pull-request APIs.
2//!
3//! The read combines pull-request facts, formal reviews, inline threads,
4//! unanchored comments and outstanding requests into one provider-neutral
5//! observation. GitHub's REST review and issue-comment records identify
6//! reviews, apps and unanchored comments; GraphQL supplies thread locations,
7//! resolution, complete comment sequences and outstanding requests. The
8//! provider joins them here so callers never correlate GitHub entities.
9//!
10//! Checks are read separately, per commit, from GitHub's check-runs endpoint,
11//! which reports the current run of each check within each check suite on that
12//! commit. Runs sharing a name across suites all remain. GitHub's legacy commit
13//! statuses are a different mechanism with its own endpoint and are not read
14//! here.
15
16use async_trait::async_trait;
17use interprex::{
18    ChangeRequest, ChangeRequestCommentsProvider, ChangeRequestHead, ChangeRequestNumber,
19    CheckOutcome, CheckRun, CodeReviewsProvider, FindingResolution, FindingResolutionRecord,
20    FindingResolutionReply, ProviderError, Repository, Result, ReviewCommentId,
21    ReviewRequestTarget, ReviewRequestTargetInspection, ReviewTargetsProvider, ReviewThreadId,
22    ReviewThreadStatus, ReviewerApplicationsProvider,
23};
24use octocrab::Page;
25use serde::Deserialize;
26use serde_json::json;
27
28use crate::{GithubProvider, client::external};
29
30mod actors;
31mod branch_updates;
32mod change_requests;
33pub(crate) mod checks;
34mod finding_resolutions;
35mod review_publications;
36mod review_requests;
37mod review_threads;
38mod reviewer_applications;
39mod target_inspections;
40mod text_records;
41
42use change_requests::{
43    GithubPullRequestNumber, head_filter, normalize_change_request, number, observed_head,
44    thread_references_missing_review,
45};
46use checks::{conclusion, normalize_check_run};
47use finding_resolutions::{
48    ADD_THREAD_REPLY, AddThreadReplyData, RESOLVE_THREAD, ResolveThreadData,
49    github_resolution_reply,
50};
51use review_requests::REQUEST_REVIEWS_BY_LOGIN;
52
53#[derive(Deserialize)]
54struct CreatedUnanchoredComment {
55    node_id: String,
56}
57
58const MARK_READY: &str = r#"
59mutation MarkReady($pullRequestId: ID!) {
60  markPullRequestReadyForReview(input: {pullRequestId: $pullRequestId}) {
61    pullRequest { id isDraft }
62  }
63}"#;
64
65#[derive(Default, Deserialize, PartialEq)]
66struct PageInfo {
67    #[serde(rename = "hasNextPage")]
68    has_next_page: bool,
69    #[serde(rename = "endCursor")]
70    end_cursor: Option<String>,
71}
72
73fn continuation_cursor(
74    page_info: &PageInfo,
75    operation: &'static str,
76    collection: &str,
77) -> Result<Option<String>> {
78    if !page_info.has_next_page {
79        return Ok(None);
80    }
81    page_info
82        .end_cursor
83        .clone()
84        .map(Some)
85        .ok_or_else(|| ProviderError::External {
86            provider: "github",
87            operation,
88            message: format!("GitHub reported another {collection} page without an end cursor"),
89        })
90}
91
92#[async_trait]
93impl CodeReviewsProvider for GithubProvider {
94    #[tracing::instrument(
95        name = "interprex.provider.code_reviews.change_request",
96        skip_all,
97        fields(interprex.provider.name = "github")
98    )]
99    async fn change_request(
100        &self,
101        repository: &Repository,
102        number: ChangeRequestNumber,
103    ) -> Result<ChangeRequest> {
104        let pull_request = self.github_pull_request(repository, number).await?;
105        let mut reviews = self.github_reviews(repository, number).await?;
106        let mut threads = self.github_review_threads(repository, number).await?;
107        if thread_references_missing_review(&reviews, &threads) {
108            reviews = self.github_reviews(repository, number).await?;
109            threads = self.github_review_threads(repository, number).await?;
110        }
111        let requests = self.github_review_requests(repository, number).await?;
112        // The timeline is a whole paginated read on its own and the request
113        // times it carries describe outstanding requests only, so it is read
114        // when at least one outstanding request names a reviewer to match.
115        let request_events = if requests
116            .iter()
117            .any(|request| request.target_key().is_some())
118        {
119            self.github_review_request_events(repository, number)
120                .await?
121        } else {
122            Vec::new()
123        };
124        let unanchored_comments = self.github_unanchored_comments(repository, number).await?;
125        let mut pull_request = pull_request;
126        if pull_request.is_open() {
127            let target = self
128                .target_branch_revision(repository, &pull_request.base.branch)
129                .await?;
130            pull_request.observe_target(target);
131        }
132        normalize_change_request(
133            pull_request,
134            reviews,
135            threads,
136            requests,
137            request_events,
138            unanchored_comments,
139        )
140    }
141
142    #[tracing::instrument(
143        name = "interprex.provider.code_reviews.open_change_requests",
144        skip_all,
145        fields(interprex.provider.name = "github")
146    )]
147    async fn open_change_requests(
148        &self,
149        repository: &Repository,
150        head: &ChangeRequestHead,
151    ) -> Result<Vec<ChangeRequestNumber>> {
152        let filter = head_filter(head);
153        let page: Page<GithubPullRequestNumber> = self
154            .user()?
155            .get(
156                format!("/repos/{repository}/pulls"),
157                Some(&[
158                    ("head", filter.as_str()),
159                    ("state", "open"),
160                    ("per_page", "100"),
161                ]),
162            )
163            .await
164            .map_err(|error| external("list open change requests", error))?;
165        let listed = self
166            .user()?
167            .all_pages(page)
168            .await
169            .map_err(|error| external("list open change requests", error))?;
170        let mut numbers = Vec::new();
171        for pull_request in listed {
172            match observed_head(&pull_request.head)? {
173                Some(observed) if &observed == head => numbers.push(number(pull_request.number)?),
174                // The filter addresses an owner and a branch, so another
175                // repository of the same owner can answer it.
176                Some(_) => {}
177                None => {
178                    return Err(ProviderError::Unrepresentable {
179                        provider: "github",
180                        fact: format!(
181                            "change request {} proposes branch {} from a repository GitHub no longer identifies, so whether it proposes {} cannot be established",
182                            pull_request.number,
183                            pull_request.head.branch,
184                            head.repository()
185                        ),
186                    });
187                }
188            }
189        }
190        Ok(numbers)
191    }
192
193    #[tracing::instrument(
194        name = "interprex.provider.code_reviews.resolve_thread",
195        skip_all,
196        fields(interprex.provider.name = "github")
197    )]
198    async fn resolve_thread(
199        &self,
200        _repository: &Repository,
201        _number: ChangeRequestNumber,
202        thread_id: &ReviewThreadId,
203    ) -> Result<()> {
204        let response: ResolveThreadData = self
205            .user()?
206            .graphql(&json!({
207                "query": RESOLVE_THREAD,
208                "variables": { "threadId": thread_id.as_str() }
209            }))
210            .await
211            .map_err(|error| external("resolve review thread", error))?;
212        let resolved = response.resolve_review_thread.thread;
213        if resolved.id == thread_id.as_str() && resolved.is_resolved {
214            Ok(())
215        } else {
216            Err(ProviderError::External {
217                provider: "github",
218                operation: "resolve review thread",
219                message: format!(
220                    "GitHub returned thread {} with isResolved={} for requested thread {}",
221                    resolved.id,
222                    resolved.is_resolved,
223                    thread_id.as_str()
224                ),
225            })
226        }
227    }
228
229    #[tracing::instrument(
230        name = "interprex.provider.code_reviews.resolve_finding",
231        skip_all,
232        fields(interprex.provider.name = "github")
233    )]
234    async fn resolve_finding(
235        &self,
236        repository: &Repository,
237        number: ChangeRequestNumber,
238        thread_id: &ReviewThreadId,
239        resolution: FindingResolution,
240        reply: &FindingResolutionReply,
241    ) -> Result<()> {
242        let change_request = self.change_request(repository, number).await?;
243        let finding = change_request
244            .reviews
245            .iter()
246            .flat_map(|review| &review.findings)
247            .find(|finding| &finding.id == thread_id)
248            .ok_or_else(|| ProviderError::NotFound {
249                entity: format!("finding thread {}", thread_id.as_str()),
250            })?;
251        if let Some(FindingResolutionRecord::Unsupported {
252            metadata_format, ..
253        }) = &finding.resolution
254        {
255            return Err(ProviderError::Unrepresentable {
256                provider: "github",
257                fact: format!(
258                    "finding thread {} contains unsupported resolution metadata format {metadata_format}",
259                    thread_id.as_str()
260                ),
261            });
262        }
263        if matches!(
264            &finding.resolution,
265            Some(FindingResolutionRecord::Supported {
266                resolution: recorded,
267                ..
268            }) if *recorded == resolution
269        ) {
270            return if finding.status == ReviewThreadStatus::Resolved {
271                Ok(())
272            } else {
273                self.resolve_thread(repository, number, thread_id).await
274            };
275        }
276        let already_resolved = finding.status == ReviewThreadStatus::Resolved;
277        let body = github_resolution_reply(resolution, reply.as_str());
278        let response: AddThreadReplyData = self
279            .user()?
280            .graphql(&json!({
281                "query": ADD_THREAD_REPLY,
282                "variables": { "threadId": thread_id.as_str(), "body": body }
283            }))
284            .await
285            .map_err(|error| external("record finding resolution", error))?;
286        if response
287            .add_pull_request_review_thread_reply
288            .comment
289            .id
290            .is_empty()
291        {
292            return Err(ProviderError::External {
293                provider: "github",
294                operation: "record finding resolution",
295                message: "GitHub returned an empty reply identifier".to_owned(),
296            });
297        }
298        if already_resolved {
299            Ok(())
300        } else {
301            self.resolve_thread(repository, number, thread_id).await
302        }
303    }
304
305    #[tracing::instrument(
306        name = "interprex.provider.code_reviews.request_reviewers",
307        skip_all,
308        fields(interprex.provider.name = "github")
309    )]
310    async fn request_reviewers(
311        &self,
312        repository: &Repository,
313        number: ChangeRequestNumber,
314        reviewers: &[ReviewRequestTarget],
315    ) -> Result<()> {
316        let pull_request = self.github_pull_request(repository, number).await?;
317        let mut user_logins = Vec::new();
318        let mut bot_logins = Vec::new();
319        let mut team_slugs = Vec::new();
320        for reviewer in reviewers {
321            match reviewer {
322                ReviewRequestTarget::User(login) => user_logins.push(login.as_str()),
323                ReviewRequestTarget::Bot(login) => bot_logins.push(if login.ends_with("[bot]") {
324                    login.clone()
325                } else {
326                    format!("{login}[bot]")
327                }),
328                ReviewRequestTarget::Team(identifier) => team_slugs.push(identifier.as_str()),
329            }
330        }
331        let _: serde_json::Value = self
332            .user()?
333            .graphql(&json!({
334                "query": REQUEST_REVIEWS_BY_LOGIN,
335                "variables": {
336                    "pullRequestId": pull_request.node_id,
337                    "userLogins": user_logins,
338                    "botLogins": bot_logins,
339                    "teamSlugs": team_slugs,
340                }
341            }))
342            .await
343            .map_err(|error| external("request code reviewers", error))?;
344        Ok(())
345    }
346
347    #[tracing::instrument(
348        name = "interprex.provider.code_reviews.mark_ready",
349        skip_all,
350        fields(interprex.provider.name = "github")
351    )]
352    async fn mark_ready(&self, repository: &Repository, number: ChangeRequestNumber) -> Result<()> {
353        let pull_request = self.github_pull_request(repository, number).await?;
354        let _: serde_json::Value = self
355            .user()?
356            .graphql(&json!({
357                "query": MARK_READY,
358                "variables": { "pullRequestId": pull_request.node_id }
359            }))
360            .await
361            .map_err(|error| external("mark change request ready", error))?;
362        Ok(())
363    }
364
365    #[tracing::instrument(
366        name = "interprex.provider.code_reviews.checks",
367        skip_all,
368        fields(interprex.provider.name = "github")
369    )]
370    async fn checks(&self, repository: &Repository, head_sha: &str) -> Result<Vec<CheckRun>> {
371        self.github_check_runs(repository, head_sha)
372            .await?
373            .into_iter()
374            .map(normalize_check_run)
375            .collect()
376    }
377
378    #[tracing::instrument(
379        name = "interprex.provider.code_reviews.publish_check",
380        skip_all,
381        fields(interprex.provider.name = "github")
382    )]
383    async fn publish_check(
384        &self,
385        repository: &Repository,
386        app_name: &str,
387        outcome: &CheckOutcome,
388    ) -> Result<()> {
389        let _: serde_json::Value = self
390            .app(app_name)?
391            .post(
392                format!("/repos/{repository}/check-runs"),
393                Some(&json!({
394                    "name": outcome.name,
395                    "head_sha": outcome.head_sha,
396                    "status": "completed",
397                    "conclusion": conclusion(&outcome.conclusion),
398                    "output": { "title": outcome.name, "summary": outcome.summary }
399                })),
400            )
401            .await
402            .map_err(|error| external("publish change request check", error))?;
403        Ok(())
404    }
405}
406
407#[async_trait]
408impl ChangeRequestCommentsProvider for GithubProvider {
409    #[tracing::instrument(
410        name = "interprex.provider.code_reviews.create_unanchored_comment",
411        skip_all,
412        fields(interprex.provider.name = "github")
413    )]
414    async fn create_unanchored_comment(
415        &self,
416        repository: &Repository,
417        number: ChangeRequestNumber,
418        body: &str,
419    ) -> Result<ReviewCommentId> {
420        let response: CreatedUnanchoredComment = self
421            .user()?
422            .post(
423                format!("/repos/{repository}/issues/{}/comments", number.get()),
424                Some(&json!({ "body": body })),
425            )
426            .await
427            .map_err(|error| external("create unanchored comment", error))?;
428        ReviewCommentId::new(response.node_id).map_err(|error| ProviderError::Unrepresentable {
429            provider: "github",
430            fact: error.to_string(),
431        })
432    }
433}
434
435#[async_trait]
436impl ReviewTargetsProvider for GithubProvider {
437    #[tracing::instrument(
438        name = "interprex.provider.code_reviews.inspect_review_request_target",
439        skip_all,
440        fields(interprex.provider.name = "github")
441    )]
442    async fn inspect_review_request_target(
443        &self,
444        repository: &Repository,
445        target: &ReviewRequestTarget,
446    ) -> Result<ReviewRequestTargetInspection> {
447        self.github_review_request_target(repository, target).await
448    }
449}
450
451#[async_trait]
452impl ReviewerApplicationsProvider for GithubProvider {
453    #[tracing::instrument(
454        name = "interprex.provider.code_reviews.resolve_reviewer_application",
455        skip_all,
456        fields(interprex.provider.name = "github")
457    )]
458    async fn resolve_reviewer_application(
459        &self,
460        repository: &Repository,
461        slug: &str,
462    ) -> Result<interprex::ReviewerApplication> {
463        self.github_reviewer_application(repository, slug).await
464    }
465}