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