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