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