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