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