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::{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
44#[async_trait]
45impl ReviewProvider for GitHubReviewProvider {
46    async fn comment(&self, pr_number: u64, body: &str) -> Result<ReviewData> {
47        debug!(repo = %self.repo, number = pr_number, "spawning `gh pr review --comment`");
48
49        // 1. 执行 gh pr review --comment(不返回 JSON)
50        let number_str = pr_number.to_string();
51        let output = tokio::process::Command::new("gh")
52            .args(["pr", "review"])
53            .arg(&number_str)
54            .arg("--comment")
55            .arg("--body")
56            .arg(body)
57            .arg("--repo")
58            .arg(&self.repo)
59            .output()
60            .await
61            .map_err(|e| CoreError::Platform(format!("Failed to spawn gh: {e}")))?;
62
63        if !output.status.success() {
64            return Err(parse_gh_error(&output.stderr).into());
65        }
66
67        // 2. 使用 gh api 获取该 PR 的最新 review
68        self.fetch_latest_review(pr_number).await
69    }
70
71    async fn approve(&self, pr_number: u64, body: Option<&str>) -> Result<ReviewData> {
72        debug!(repo = %self.repo, number = pr_number, "spawning `gh pr review --approve`");
73
74        let mut cmd = tokio::process::Command::new("gh");
75        cmd.args(["pr", "review"])
76            .arg(pr_number.to_string())
77            .arg("--approve")
78            .arg("--repo")
79            .arg(&self.repo);
80
81        if let Some(b) = body {
82            cmd.arg("--body").arg(b);
83        }
84
85        let output = cmd
86            .output()
87            .await
88            .map_err(|e| CoreError::Platform(format!("Failed to spawn gh: {e}")))?;
89
90        if !output.status.success() {
91            let gh_err = parse_gh_error(&output.stderr);
92            // 检测 "approve your own pull request" 错误
93            if gh_err
94                .user_message
95                .contains("approve your own pull request")
96            {
97                return Err(CoreError::Platform(
98                    "GitHub 不允许批准自己的 PR。可以请求其他维护者审查。".to_string(),
99                ));
100            }
101            return Err(gh_err.into());
102        }
103
104        // 使用 gh api 获取该 PR 的最新 review
105        self.fetch_latest_review(pr_number).await
106    }
107
108    async fn request_changes(&self, pr_number: u64, body: &str) -> Result<ReviewData> {
109        debug!(repo = %self.repo, number = pr_number, "spawning `gh pr review --request-changes`");
110
111        let output = tokio::process::Command::new("gh")
112            .args(["pr", "review"])
113            .arg(pr_number.to_string())
114            .arg("--request-changes")
115            .arg("--body")
116            .arg(body)
117            .arg("--repo")
118            .arg(&self.repo)
119            .output()
120            .await
121            .map_err(|e| CoreError::Platform(format!("Failed to spawn gh: {e}")))?;
122
123        if !output.status.success() {
124            return Err(parse_gh_error(&output.stderr).into());
125        }
126
127        // 使用 gh api 获取该 PR 的最新 review
128        self.fetch_latest_review(pr_number).await
129    }
130
131    async fn submit_review(
132        &self,
133        pr_number: u64,
134        event: ReviewState,
135        body: Option<&str>,
136    ) -> Result<ReviewData> {
137        debug!(repo = %self.repo, number = pr_number, ?event, "spawning `gh pr review`");
138
139        let mut cmd = tokio::process::Command::new("gh");
140        cmd.args(["pr", "review"])
141            .arg(pr_number.to_string())
142            .arg("--repo")
143            .arg(&self.repo);
144
145        match event {
146            ReviewState::Approved => {
147                cmd.arg("--approve");
148            }
149            ReviewState::ChangesRequested => {
150                cmd.arg("--request-changes");
151            }
152            ReviewState::Commented => {
153                cmd.arg("--comment");
154            }
155        }
156
157        if let Some(b) = body {
158            cmd.arg("--body").arg(b);
159        }
160
161        let output = cmd
162            .output()
163            .await
164            .map_err(|e| CoreError::Platform(format!("Failed to spawn gh: {e}")))?;
165
166        if !output.status.success() {
167            let gh_err = parse_gh_error(&output.stderr);
168            if gh_err
169                .user_message
170                .contains("approve your own pull request")
171            {
172                return Err(CoreError::Platform(
173                    "GitHub 不允许批准自己的 PR。可以请求其他维护者审查。".to_string(),
174                ));
175            }
176            return Err(gh_err.into());
177        }
178
179        // 使用 gh api 获取该 PR 的最新 review
180        self.fetch_latest_review(pr_number).await
181    }
182}
183
184impl GitHubReviewProvider {
185    /// 使用 gh api 获取指定 PR 的最新 review。
186    ///
187    /// 在提交 review 后调用,以获取完整的 review 数据(ID、状态、时间戳等)。
188    async fn fetch_latest_review(&self, pr_number: u64) -> Result<ReviewData> {
189        let api_path = format!(
190            "repos/{repo}/pulls/{number}/reviews?per_page=1",
191            repo = self.repo,
192            number = pr_number
193        );
194
195        let output = tokio::process::Command::new("gh")
196            .args(["api", &api_path])
197            .output()
198            .await
199            .map_err(|e| CoreError::Platform(format!("Failed to spawn gh api: {e}")))?;
200
201        if !output.status.success() {
202            let gh_err = String::from_utf8_lossy(&output.stderr);
203            return Err(CoreError::Platform(format!(
204                "Failed to fetch review via gh api: {gh_err}"
205            )));
206        }
207
208        let reviews: Vec<GitHubReviewApiResponse> =
209            serde_json::from_slice(&output.stdout).map_err(CoreError::Serialization)?;
210
211        let review = reviews
212            .into_iter()
213            .next()
214            .ok_or_else(|| CoreError::Platform("No review returned from gh api".to_string()))?;
215
216        Ok(review.into())
217    }
218}
219
220/// GitHub API Review 响应结构。
221///
222/// 用于解析 `gh api repos/{owner}/{repo}/pulls/{number}/reviews` 的返回数据。
223#[derive(Debug, Clone, serde::Deserialize)]
224pub struct GitHubReviewApiResponse {
225    /// Review 的 numeric ID。
226    pub id: u64,
227    /// Review 的状态(`APPROVED`, `CHANGES_REQUESTED`, `COMMENTED` 等)。
228    pub state: String,
229    /// Review 正文(Markdown,可选)。
230    #[serde(default)]
231    pub body: Option<String>,
232    /// 审查人。
233    pub user: GitHubUser,
234    /// 提交时间(UTC,ISO 8601 格式)。
235    pub submitted_at: String,
236}
237
238impl From<GitHubReviewApiResponse> for ReviewData {
239    fn from(api: GitHubReviewApiResponse) -> Self {
240        Self {
241            id: api.id,
242            state: match api.state.as_str() {
243                "APPROVED" => ReviewState::Approved,
244                "CHANGES_REQUESTED" => ReviewState::ChangesRequested,
245                _ => ReviewState::Commented,
246            },
247            body: api.body,
248            author: gitflow_core::types::UserSummary {
249                login: api.user.login,
250                id: api.user.id.to_string(),
251            },
252            submitted_at: api
253                .submitted_at
254                .parse()
255                .unwrap_or_else(|_| chrono::Utc::now()),
256        }
257    }
258}
259
260#[cfg(test)]
261mod tests {
262    use super::*;
263
264    #[test]
265    fn test_should_construct_github_review_provider() {
266        let provider = GitHubReviewProvider::new("octocat/hello-world");
267        assert_eq!(provider.repo, "octocat/hello-world");
268    }
269
270    #[test]
271    fn test_should_construct_github_review_provider_from_string() {
272        let repo = String::from("octocat/hello-world");
273        let provider = GitHubReviewProvider::new(repo);
274        assert_eq!(provider.repo, "octocat/hello-world");
275    }
276
277    #[test]
278    fn test_should_deserialize_review_data_from_gh_output() {
279        // 模拟 `gh pr review --json ...` 的实际输出
280        let gh_json = br#"{
281            "id": 2001,
282            "state": "approved",
283            "body": "Looks great, LGTM!",
284            "author": {"login": "reviewer", "id": "42"},
285            "submittedAt": "2026-05-20T14:30:00Z"
286        }"#;
287
288        let review: ReviewData = serde_json::from_slice(gh_json).expect("valid ReviewData JSON");
289        assert_eq!(review.id, 2001);
290        assert_eq!(review.state, ReviewState::Approved);
291        assert_eq!(review.body.as_deref(), Some("Looks great, LGTM!"));
292        assert_eq!(review.author.login, "reviewer");
293        assert_eq!(review.author.id, "42");
294    }
295
296    #[test]
297    fn test_should_deserialize_changes_requested_review_from_gh_output() {
298        let gh_json = br#"{
299            "id": 2002,
300            "state": "changes_requested",
301            "body": "Please fix the error handling",
302            "author": {"login": "senior-dev", "id": "7"},
303            "submittedAt": "2026-05-21T09:00:00Z"
304        }"#;
305
306        let review: ReviewData = serde_json::from_slice(gh_json).expect("valid ReviewData");
307        assert_eq!(review.state, ReviewState::ChangesRequested);
308        assert_eq!(
309            review.body.as_deref(),
310            Some("Please fix the error handling")
311        );
312    }
313
314    #[test]
315    fn test_should_deserialize_commented_review_from_gh_output() {
316        let gh_json = br#"{
317            "id": 2003,
318            "state": "commented",
319            "body": null,
320            "author": {"login": "observer", "id": "15"},
321            "submittedAt": "2026-05-22T11:00:00Z"
322        }"#;
323
324        let review: ReviewData = serde_json::from_slice(gh_json).expect("valid ReviewData");
325        assert_eq!(review.state, ReviewState::Commented);
326        assert!(review.body.is_none());
327    }
328
329    #[test]
330    fn test_should_debug_format_provider() {
331        let provider = GitHubReviewProvider::new("octocat/hello-world");
332        let debug = format!("{provider:?}");
333        assert!(debug.contains("GitHubReviewProvider"));
334        assert!(debug.contains("octocat/hello-world"));
335    }
336
337    #[test]
338    fn test_should_create_provider_with_different_repos() {
339        let r1 = GitHubReviewProvider::new("org/repo-a");
340        let r2 = GitHubReviewProvider::new("org/repo-b");
341        assert_eq!(r1.repo, "org/repo-a");
342        assert_eq!(r2.repo, "org/repo-b");
343    }
344
345    #[test]
346    fn test_should_clone_github_review_provider() {
347        let original = GitHubReviewProvider::new("owner/repo");
348        let cloned = original.clone();
349        assert_eq!(original.repo, cloned.repo);
350    }
351
352    #[test]
353    fn test_should_deserialize_github_review_api_response() {
354        let json = r#"{
355            "id": 12345,
356            "state": "APPROVED",
357            "body": "LGTM",
358            "user": {"login": "octocat", "id": 1},
359            "submitted_at": "2026-08-03T10:00:00Z"
360        }"#;
361
362        let response: GitHubReviewApiResponse = serde_json::from_str(json).expect("valid response");
363
364        assert_eq!(response.id, 12345);
365        assert_eq!(response.state, "APPROVED");
366        assert_eq!(response.body, Some("LGTM".to_string()));
367        assert_eq!(response.user.login, "octocat");
368        assert_eq!(response.user.id, 1);
369        assert_eq!(response.submitted_at, "2026-08-03T10:00:00Z");
370    }
371
372    #[test]
373    fn test_should_convert_github_review_api_response_to_review_data() {
374        let api_response = GitHubReviewApiResponse {
375            id: 12345,
376            state: "APPROVED".to_string(),
377            body: Some("LGTM".to_string()),
378            user: GitHubUser {
379                login: "octocat".to_string(),
380                id: 1,
381            },
382            submitted_at: "2026-08-03T10:00:00Z".to_string(),
383        };
384
385        let review_data: ReviewData = api_response.into();
386
387        assert_eq!(review_data.id, 12345);
388        assert_eq!(review_data.state, ReviewState::Approved);
389        assert_eq!(review_data.body, Some("LGTM".to_string()));
390        assert_eq!(review_data.author.login, "octocat");
391        assert_eq!(review_data.author.id, "1");
392    }
393
394    #[test]
395    fn test_should_convert_all_review_states() {
396        let states = vec![
397            ("APPROVED", ReviewState::Approved),
398            ("CHANGES_REQUESTED", ReviewState::ChangesRequested),
399            ("COMMENTED", ReviewState::Commented),
400        ];
401
402        for (state_str, expected_state) in states {
403            let api_response = GitHubReviewApiResponse {
404                id: 1,
405                state: state_str.to_string(),
406                body: None,
407                user: GitHubUser {
408                    login: "test".to_string(),
409                    id: 1,
410                },
411                submitted_at: "2026-08-03T10:00:00Z".to_string(),
412            };
413
414            let review_data: ReviewData = api_response.into();
415            assert_eq!(review_data.state, expected_state);
416        }
417    }
418}