Skip to main content

gitflow_github/
review.rs

1//! GitHub Review 提供者实现。
2//!
3//! 通过 `gh` CLI 实现 [`ReviewProvider`] trait,支持 PR 审查的评论、
4//! 批准、要求修改及提交审查。
5//! 所有方法通过 `tokio::process::Command` 调用 `gh`,捕获 stdout 并解析 JSON。
6
7use async_trait::async_trait;
8use gitflow_core::{
9    CoreError, Result,
10    review::{ReviewData, ReviewProvider, ReviewState},
11};
12use tracing::debug;
13
14use crate::{datetime::parse_api_datetime, error::parse_gh_error, issue::GitHubUser};
15
16/// GitHub Review 提供者,通过 `gh` CLI 操作。
17///
18/// 该结构体通过调用 `gh` CLI 实现 [`ReviewProvider`] trait 的所有方法,
19/// 使上层命令能够以统一的方式操作 GitHub PR 审查。
20///
21/// # Examples
22///
23/// ```no_run
24/// use gitflow_github::GitHubReviewProvider;
25///
26/// let provider = GitHubReviewProvider::new("octocat/hello-world");
27/// ```
28#[derive(Debug, Clone)]
29pub struct GitHubReviewProvider {
30    /// GitHub `owner/repo`,如 `"byx-darwin/gitflow-cli"`。
31    repo: String,
32}
33
34impl GitHubReviewProvider {
35    /// 创建新的 GitHub Review 提供者。
36    ///
37    /// `repo` 格式为 `owner/repo`。
38    #[must_use]
39    pub fn new(repo: impl Into<String>) -> Self {
40        Self { repo: repo.into() }
41    }
42
43    /// Create a new provider from a shared [`Session`].
44    ///
45    /// This enables state reuse across multiple operations in workflow chains.
46    #[must_use]
47    pub fn with_session(session: &gitflow_core::Session) -> Self {
48        Self {
49            repo: session.repo.clone(),
50        }
51    }
52}
53
54#[async_trait]
55impl ReviewProvider for GitHubReviewProvider {
56    async fn comment(&self, pr_number: u64, body: &str) -> Result<ReviewData> {
57        debug!(repo = %self.repo, number = pr_number, "spawning `gh pr review --comment`");
58
59        // 1. 执行 gh pr review --comment(不返回 JSON)
60        let number_str = pr_number.to_string();
61        let output = tokio::process::Command::new("gh")
62            .args(["pr", "review"])
63            .arg(&number_str)
64            .arg("--comment")
65            .arg("--body")
66            .arg(body)
67            .arg("--repo")
68            .arg(&self.repo)
69            .output()
70            .await
71            .map_err(|e| CoreError::Platform(format!("Failed to spawn gh: {e}")))?;
72
73        if !output.status.success() {
74            return Err(parse_gh_error(&output.stderr).into());
75        }
76
77        // 2. 使用 gh api 获取该 PR 的最新 review
78        self.fetch_latest_review(pr_number).await
79    }
80
81    async fn approve(&self, pr_number: u64, body: Option<&str>) -> Result<ReviewData> {
82        debug!(repo = %self.repo, number = pr_number, "spawning `gh pr review --approve`");
83
84        let mut cmd = tokio::process::Command::new("gh");
85        cmd.args(["pr", "review"])
86            .arg(pr_number.to_string())
87            .arg("--approve")
88            .arg("--repo")
89            .arg(&self.repo);
90
91        if let Some(b) = body {
92            cmd.arg("--body").arg(b);
93        }
94
95        let output = cmd
96            .output()
97            .await
98            .map_err(|e| CoreError::Platform(format!("Failed to spawn gh: {e}")))?;
99
100        if !output.status.success() {
101            let gh_err = parse_gh_error(&output.stderr);
102            // 检测 "approve your own pull request" 错误
103            if gh_err
104                .user_message
105                .contains("approve your own pull request")
106            {
107                return Err(CoreError::Platform(
108                    "GitHub 不允许批准自己的 PR。可以请求其他维护者审查。".to_string(),
109                ));
110            }
111            return Err(gh_err.into());
112        }
113
114        // 使用 gh api 获取该 PR 的最新 review
115        self.fetch_latest_review(pr_number).await
116    }
117
118    async fn request_changes(&self, pr_number: u64, body: &str) -> Result<ReviewData> {
119        debug!(repo = %self.repo, number = pr_number, "spawning `gh pr review --request-changes`");
120
121        let output = tokio::process::Command::new("gh")
122            .args(["pr", "review"])
123            .arg(pr_number.to_string())
124            .arg("--request-changes")
125            .arg("--body")
126            .arg(body)
127            .arg("--repo")
128            .arg(&self.repo)
129            .output()
130            .await
131            .map_err(|e| CoreError::Platform(format!("Failed to spawn gh: {e}")))?;
132
133        if !output.status.success() {
134            return Err(parse_gh_error(&output.stderr).into());
135        }
136
137        // 使用 gh api 获取该 PR 的最新 review
138        self.fetch_latest_review(pr_number).await
139    }
140
141    async fn submit_review(
142        &self,
143        pr_number: u64,
144        event: ReviewState,
145        body: Option<&str>,
146    ) -> Result<ReviewData> {
147        debug!(repo = %self.repo, number = pr_number, ?event, "spawning `gh pr review`");
148
149        let mut cmd = tokio::process::Command::new("gh");
150        cmd.args(["pr", "review"])
151            .arg(pr_number.to_string())
152            .arg("--repo")
153            .arg(&self.repo);
154
155        match event {
156            ReviewState::Approved => {
157                cmd.arg("--approve");
158            }
159            ReviewState::ChangesRequested => {
160                cmd.arg("--request-changes");
161            }
162            ReviewState::Commented => {
163                cmd.arg("--comment");
164            }
165        }
166
167        if let Some(b) = body {
168            cmd.arg("--body").arg(b);
169        }
170
171        let output = cmd
172            .output()
173            .await
174            .map_err(|e| CoreError::Platform(format!("Failed to spawn gh: {e}")))?;
175
176        if !output.status.success() {
177            let gh_err = parse_gh_error(&output.stderr);
178            if gh_err
179                .user_message
180                .contains("approve your own pull request")
181            {
182                return Err(CoreError::Platform(
183                    "GitHub 不允许批准自己的 PR。可以请求其他维护者审查。".to_string(),
184                ));
185            }
186            return Err(gh_err.into());
187        }
188
189        // 使用 gh api 获取该 PR 的最新 review
190        self.fetch_latest_review(pr_number).await
191    }
192}
193
194impl GitHubReviewProvider {
195    /// 使用 gh api 获取指定 PR 的最新 review。
196    ///
197    /// 在提交 review 后调用,以获取完整的 review 数据(ID、状态、时间戳等)。
198    async fn fetch_latest_review(&self, pr_number: u64) -> Result<ReviewData> {
199        let api_path = format!(
200            "repos/{repo}/pulls/{number}/reviews?per_page=1",
201            repo = self.repo,
202            number = pr_number
203        );
204
205        let output = tokio::process::Command::new("gh")
206            .args(["api", &api_path])
207            .output()
208            .await
209            .map_err(|e| CoreError::Platform(format!("Failed to spawn gh api: {e}")))?;
210
211        if !output.status.success() {
212            let gh_err = String::from_utf8_lossy(&output.stderr);
213            return Err(CoreError::Platform(format!(
214                "Failed to fetch review via gh api: {gh_err}"
215            )));
216        }
217
218        let reviews: Vec<GitHubReviewApiResponse> =
219            serde_json::from_slice(&output.stdout).map_err(CoreError::Serialization)?;
220
221        let review = reviews
222            .into_iter()
223            .next()
224            .ok_or_else(|| CoreError::Platform("No review returned from gh api".to_string()))?;
225
226        Ok(review.into())
227    }
228}
229
230/// GitHub API Review 响应结构。
231///
232/// 用于解析 `gh api repos/{owner}/{repo}/pulls/{number}/reviews` 的返回数据。
233#[derive(Debug, Clone, serde::Deserialize)]
234pub struct GitHubReviewApiResponse {
235    /// Review 的 numeric ID。
236    pub id: u64,
237    /// Review 的状态(`APPROVED`, `CHANGES_REQUESTED`, `COMMENTED` 等)。
238    pub state: String,
239    /// Review 正文(Markdown,可选)。
240    #[serde(default)]
241    pub body: Option<String>,
242    /// 审查人。
243    pub user: GitHubUser,
244    /// 提交时间(UTC,ISO 8601 格式)。
245    pub submitted_at: String,
246}
247
248impl From<GitHubReviewApiResponse> for ReviewData {
249    fn from(api: GitHubReviewApiResponse) -> Self {
250        Self {
251            id: api.id,
252            state: match api.state.as_str() {
253                "APPROVED" => ReviewState::Approved,
254                "CHANGES_REQUESTED" => ReviewState::ChangesRequested,
255                _ => ReviewState::Commented,
256            },
257            body: api.body,
258            author: gitflow_core::types::UserSummary {
259                login: api.user.login,
260                id: api.user.id.to_string(),
261            },
262            submitted_at: Some(parse_api_datetime(&api.submitted_at)),
263        }
264    }
265}
266
267#[cfg(test)]
268mod tests {
269    use super::*;
270
271    #[test]
272    fn test_should_construct_github_review_provider() {
273        let provider = GitHubReviewProvider::new("octocat/hello-world");
274        assert_eq!(provider.repo, "octocat/hello-world");
275    }
276
277    #[test]
278    fn test_should_construct_github_review_provider_from_string() {
279        let repo = String::from("octocat/hello-world");
280        let provider = GitHubReviewProvider::new(repo);
281        assert_eq!(provider.repo, "octocat/hello-world");
282    }
283
284    #[test]
285    fn test_should_deserialize_review_data_from_gh_output() {
286        // 模拟 `gh pr review --json ...` 的实际输出
287        let gh_json = br#"{
288            "id": 2001,
289            "state": "approved",
290            "body": "Looks great, LGTM!",
291            "author": {"login": "reviewer", "id": "42"},
292            "submittedAt": "2026-05-20T14:30:00Z"
293        }"#;
294
295        let review: ReviewData = serde_json::from_slice(gh_json).expect("valid ReviewData JSON");
296        assert_eq!(review.id, 2001);
297        assert_eq!(review.state, ReviewState::Approved);
298        assert_eq!(review.body.as_deref(), Some("Looks great, LGTM!"));
299        assert_eq!(review.author.login, "reviewer");
300        assert_eq!(review.author.id, "42");
301    }
302
303    #[test]
304    fn test_should_deserialize_changes_requested_review_from_gh_output() {
305        let gh_json = br#"{
306            "id": 2002,
307            "state": "changes_requested",
308            "body": "Please fix the error handling",
309            "author": {"login": "senior-dev", "id": "7"},
310            "submittedAt": "2026-05-21T09:00:00Z"
311        }"#;
312
313        let review: ReviewData = serde_json::from_slice(gh_json).expect("valid ReviewData");
314        assert_eq!(review.state, ReviewState::ChangesRequested);
315        assert_eq!(
316            review.body.as_deref(),
317            Some("Please fix the error handling")
318        );
319    }
320
321    #[test]
322    fn test_should_deserialize_commented_review_from_gh_output() {
323        let gh_json = br#"{
324            "id": 2003,
325            "state": "commented",
326            "body": null,
327            "author": {"login": "observer", "id": "15"},
328            "submittedAt": "2026-05-22T11:00:00Z"
329        }"#;
330
331        let review: ReviewData = serde_json::from_slice(gh_json).expect("valid ReviewData");
332        assert_eq!(review.state, ReviewState::Commented);
333        assert!(review.body.is_none());
334    }
335
336    #[test]
337    fn test_should_debug_format_provider() {
338        let provider = GitHubReviewProvider::new("octocat/hello-world");
339        let debug = format!("{provider:?}");
340        assert!(debug.contains("GitHubReviewProvider"));
341        assert!(debug.contains("octocat/hello-world"));
342    }
343
344    #[test]
345    fn test_should_create_provider_with_different_repos() {
346        let r1 = GitHubReviewProvider::new("org/repo-a");
347        let r2 = GitHubReviewProvider::new("org/repo-b");
348        assert_eq!(r1.repo, "org/repo-a");
349        assert_eq!(r2.repo, "org/repo-b");
350    }
351
352    #[test]
353    fn test_should_clone_github_review_provider() {
354        let original = GitHubReviewProvider::new("owner/repo");
355        let cloned = original.clone();
356        assert_eq!(original.repo, cloned.repo);
357    }
358
359    #[test]
360    fn test_should_deserialize_github_review_api_response() {
361        let json = r#"{
362            "id": 12345,
363            "state": "APPROVED",
364            "body": "LGTM",
365            "user": {"login": "octocat", "id": 1},
366            "submitted_at": "2026-08-03T10:00:00Z"
367        }"#;
368
369        let response: GitHubReviewApiResponse = serde_json::from_str(json).expect("valid response");
370
371        assert_eq!(response.id, 12345);
372        assert_eq!(response.state, "APPROVED");
373        assert_eq!(response.body, Some("LGTM".to_string()));
374        assert_eq!(response.user.login, "octocat");
375        assert_eq!(response.user.id, 1);
376        assert_eq!(response.submitted_at, "2026-08-03T10:00:00Z");
377    }
378
379    #[test]
380    fn test_should_convert_github_review_api_response_to_review_data() {
381        let api_response = GitHubReviewApiResponse {
382            id: 12345,
383            state: "APPROVED".to_string(),
384            body: Some("LGTM".to_string()),
385            user: GitHubUser {
386                login: "octocat".to_string(),
387                id: 1,
388            },
389            submitted_at: "2026-08-03T10:00:00Z".to_string(),
390        };
391
392        let review_data: ReviewData = api_response.into();
393
394        assert_eq!(review_data.id, 12345);
395        assert_eq!(review_data.state, ReviewState::Approved);
396        assert_eq!(review_data.body, Some("LGTM".to_string()));
397        assert_eq!(review_data.author.login, "octocat");
398        assert_eq!(review_data.author.id, "1");
399    }
400
401    #[test]
402    fn test_should_deserialize_review_with_present_submitted_at_as_some() {
403        let api_response = GitHubReviewApiResponse {
404            id: 1,
405            state: "APPROVED".to_string(),
406            body: None,
407            user: GitHubUser {
408                login: "user".to_string(),
409                id: 1,
410            },
411            submitted_at: "2026-08-03T10:00:00Z".to_string(),
412        };
413        let review_data: ReviewData = api_response.into();
414        assert!(review_data.submitted_at.is_some());
415    }
416
417    #[test]
418    fn test_should_use_epoch_for_malformed_review_timestamp() {
419        let api_response = GitHubReviewApiResponse {
420            id: 1,
421            state: "APPROVED".to_string(),
422            body: None,
423            user: GitHubUser {
424                login: "user".to_string(),
425                id: 1,
426            },
427            submitted_at: "not-a-timestamp".to_string(),
428        };
429
430        let review_data: ReviewData = api_response.into();
431        assert_eq!(review_data.submitted_at, Some(chrono::DateTime::UNIX_EPOCH));
432    }
433
434    #[test]
435    fn test_should_convert_all_review_states() {
436        let states = vec![
437            ("APPROVED", ReviewState::Approved),
438            ("CHANGES_REQUESTED", ReviewState::ChangesRequested),
439            ("COMMENTED", ReviewState::Commented),
440        ];
441
442        for (state_str, expected_state) in states {
443            let api_response = GitHubReviewApiResponse {
444                id: 1,
445                state: state_str.to_string(),
446                body: None,
447                user: GitHubUser {
448                    login: "test".to_string(),
449                    id: 1,
450                },
451                submitted_at: "2026-08-03T10:00:00Z".to_string(),
452            };
453
454            let review_data: ReviewData = api_response.into();
455            assert_eq!(review_data.state, expected_state);
456        }
457    }
458
459    #[test]
460    fn test_should_map_unknown_review_state_to_commented() {
461        let api_response = GitHubReviewApiResponse {
462            id: 99,
463            state: "PENDING".to_string(),
464            body: None,
465            user: GitHubUser {
466                login: "bot".to_string(),
467                id: 0,
468            },
469            submitted_at: "2026-08-03T10:00:00Z".to_string(),
470        };
471
472        let review_data: ReviewData = api_response.into();
473        assert_eq!(review_data.state, ReviewState::Commented);
474    }
475
476    #[test]
477    fn test_should_map_dismissed_review_state_to_commented() {
478        let api_response = GitHubReviewApiResponse {
479            id: 100,
480            state: "DISMISSED".to_string(),
481            body: Some("Outdated review".to_string()),
482            user: GitHubUser {
483                login: "admin".to_string(),
484                id: 1,
485            },
486            submitted_at: "2026-08-03T10:00:00Z".to_string(),
487        };
488
489        let review_data: ReviewData = api_response.into();
490        assert_eq!(review_data.state, ReviewState::Commented);
491        assert_eq!(review_data.id, 100);
492    }
493}