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