Skip to main content

gitflow_gitlab/
review.rs

1//! GitLab Review 提供者实现。
2//!
3//! 通过 `glab mr approve` / `glab mr revoke` / `glab mr note` CLI 实现
4//! [`ReviewProvider`] trait,支持 MR 审查的评论、批准、要求修改及提交审查。
5//! 所有方法通过 `tokio::process::Command` 调用 `glab`,捕获 stdout 并解析 JSON。
6//!
7//! glab 的审查命令与 gh 不同:
8//! - 批准使用 `glab mr approve`
9//! - 撤回使用 `glab mr revoke`
10//! - 评论使用 `glab mr note`
11//!
12//! 由于 glab 不提供统一的 `review --json` 输出,本模块在审查操作后
13//! 构造符合 [`ReviewData`] 的返回值。
14
15use async_trait::async_trait;
16use chrono::{DateTime, Utc};
17use gitflow_core::{
18    CoreError, Result,
19    review::{ReviewData, ReviewProvider, ReviewState},
20    types::UserSummary,
21};
22use serde::Deserialize;
23use tracing::debug;
24
25use crate::{
26    commit::encode_project_path,
27    error::parse_glab_error,
28    runner::{CommandRunner, RealCommandRunner},
29};
30
31/// GitLab Review 提供者,通过 `glab` CLI 操作。
32///
33/// # Examples
34///
35/// ```no_run
36/// use gitflow_gitlab::GitLabReviewProvider;
37///
38/// let provider = GitLabReviewProvider::new("gitlab-org/gitlab");
39/// ```
40#[derive(Debug, Clone)]
41pub struct GitLabReviewProvider<R: CommandRunner = RealCommandRunner> {
42    /// GitLab `namespace/project`。
43    repo: String,
44    /// 用于执行 `glab` CLI 命令的 runner。
45    runner: R,
46}
47
48impl GitLabReviewProvider<RealCommandRunner> {
49    /// 创建新的 GitLab Review 提供者。
50    ///
51    /// `repo` 格式为 `namespace/project`。
52    #[must_use]
53    pub fn new(repo: impl Into<String>) -> GitLabReviewProvider<RealCommandRunner> {
54        GitLabReviewProvider {
55            repo: repo.into(),
56            runner: RealCommandRunner,
57        }
58    }
59
60    /// Create a new provider from a shared [`Session`].
61    ///
62    /// This enables state reuse across multiple operations in workflow chains.
63    #[must_use]
64    pub fn with_session(session: &gitflow_core::Session) -> Self {
65        Self {
66            repo: session.repo.clone(),
67            runner: RealCommandRunner,
68        }
69    }
70}
71
72impl<R: CommandRunner> GitLabReviewProvider<R> {
73    /// 使用自定义 [`CommandRunner`] 创建提供者。
74    ///
75    /// 主要用于测试,可注入模拟 runner 以控制 `glab` CLI 的输出。
76    /// `repo` 格式为 `namespace/project`。
77    #[must_use]
78    pub fn with_runner(repo: impl Into<String>, runner: R) -> Self {
79        Self {
80            repo: repo.into(),
81            runner,
82        }
83    }
84}
85
86// ── 中间 API 响应类型 ──────────────────────────────────────────────
87
88/// `glab mr note --output json` 返回的 JSON 结构(用于获取审查评论 ID)。
89#[derive(Debug, Clone, Deserialize)]
90struct NoteApiResponse {
91    id: u64,
92    #[serde(default)]
93    body: String,
94    #[serde(default)]
95    author: Option<ApiUser>,
96    #[serde(default)]
97    created_at: Option<DateTime<Utc>>,
98}
99
100/// JSON 输出中的用户信息。
101#[derive(Debug, Clone, Deserialize)]
102struct ApiUser {
103    username: String,
104    #[serde(default)]
105    id: u64,
106}
107
108impl From<&ApiUser> for UserSummary {
109    fn from(u: &ApiUser) -> Self {
110        Self {
111            login: u.username.clone(),
112            id: u.id.to_string(),
113        }
114    }
115}
116
117/// `glab mr view --output json` 返回的 JSON 结构(用于获取当前用户信息)。
118#[derive(Debug, Clone, Deserialize)]
119struct MrViewResponse {
120    #[serde(default)]
121    author: Option<ApiUser>,
122}
123
124// ── trait 实现 ──────────────────────────────────────────────────────
125
126#[async_trait]
127impl<R: CommandRunner + 'static> ReviewProvider for GitLabReviewProvider<R> {
128    /// 在指定 MR 上添加审查评论。
129    ///
130    /// 调用 `glab api --method POST` 发布 note 评论并构造 [`ReviewData`]。
131    async fn comment(&self, pr_number: u64, body: &str) -> Result<ReviewData> {
132        let note = self.post_note(pr_number, body).await?;
133        let author = note.author.as_ref().map_or_else(
134            || UserSummary {
135                login: "unknown".into(),
136                id: "0".to_string(),
137            },
138            UserSummary::from,
139        );
140
141        Ok(ReviewData {
142            id: note.id,
143            state: ReviewState::Commented,
144            body: Some(note.body),
145            author,
146            submitted_at: note.created_at,
147        })
148    }
149
150    /// 批准指定 MR。
151    ///
152    /// 调用 `glab mr approve` 批准 MR,然后构造 [`ReviewData`]。
153    async fn approve(&self, pr_number: u64, body: Option<&str>) -> Result<ReviewData> {
154        debug!(repo = %self.repo, number = pr_number, "spawning `glab mr approve`");
155
156        let pr_number_str = pr_number.to_string();
157        let mut cmd_args: Vec<&str> = vec!["mr", "approve", &pr_number_str];
158
159        if let Some(b) = body {
160            cmd_args.push("--comment");
161            cmd_args.push(b);
162        }
163
164        let output = self
165            .runner
166            .run("glab", &cmd_args)
167            .await
168            .map_err(|e| CoreError::Platform(format!("Failed to spawn glab: {e}")))?;
169
170        if !output.status.success() {
171            return Err(parse_glab_error(&output.stderr).into());
172        }
173
174        let message = String::from_utf8_lossy(&output.stdout).trim().to_string();
175        let author = self.get_current_user().await.unwrap_or(UserSummary {
176            login: "unknown".into(),
177            id: "0".to_string(),
178        });
179
180        Ok(ReviewData {
181            id: 0,
182            state: ReviewState::Approved,
183            body: if message.is_empty() {
184                body.map(String::from)
185            } else {
186                Some(message)
187            },
188            author,
189            // `glab mr approve` returns no timestamp of its own, but approval
190            // is a synchronous action happening at this exact instant — this
191            // is NOT backfilling an unknown historical value (the #380/#366
192            // bug class), so Utc::now() is correct here and intentionally
193            // stays a plain value, not a fallback (#380 design §3.3).
194            submitted_at: Some(Utc::now()),
195        })
196    }
197
198    /// 对指定 MR 要求修改。
199    ///
200    /// glab 没有直接的 "request changes" 命令,通过 `glab api --method POST`
201    /// 发布包含要求修改意见的 note 评论,并标记为 `ChangesRequested` 状态。
202    async fn request_changes(&self, pr_number: u64, body: &str) -> Result<ReviewData> {
203        let changes_body = format!("Changes requested:\n\n{body}");
204        let note = self.post_note(pr_number, &changes_body).await?;
205        let author = note.author.as_ref().map_or_else(
206            || UserSummary {
207                login: "unknown".into(),
208                id: "0".to_string(),
209            },
210            UserSummary::from,
211        );
212
213        Ok(ReviewData {
214            id: note.id,
215            state: ReviewState::ChangesRequested,
216            body: Some(note.body),
217            author,
218            submitted_at: note.created_at,
219        })
220    }
221
222    /// 提交指定 MR 的审查。
223    ///
224    /// 根据 `event` 参数分别调用 `glab mr approve`、`glab mr revoke` 或
225    /// `glab mr note` 实现不同的审查操作。
226    async fn submit_review(
227        &self,
228        pr_number: u64,
229        event: ReviewState,
230        body: Option<&str>,
231    ) -> Result<ReviewData> {
232        debug!(repo = %self.repo, number = pr_number, ?event, "spawning `glab mr review`");
233
234        match event {
235            ReviewState::Approved => self.approve(pr_number, body).await,
236            ReviewState::ChangesRequested => {
237                self.request_changes(pr_number, body.unwrap_or("Changes requested."))
238                    .await
239            }
240            ReviewState::Commented => {
241                self.comment(pr_number, body.unwrap_or("Review comment."))
242                    .await
243            }
244        }
245    }
246}
247
248impl<R: CommandRunner> GitLabReviewProvider<R> {
249    /// 在指定 MR 上发布一条 note(内部辅助方法)。
250    ///
251    /// 调用 `glab api --method POST
252    /// /projects/{repo-encoded}/merge_requests/{pr_number}/notes`,
253    /// 其中 `{repo-encoded}` 为全量 URL 编码的项目路径
254    /// (如 `group/subgroup/project` → `group%2Fsubgroup%2Fproject`)。
255    ///
256    /// # Errors
257    ///
258    /// 当 MR 不存在或 `glab` CLI 调用失败时返回错误。
259    async fn post_note(&self, pr_number: u64, body: &str) -> Result<NoteApiResponse> {
260        debug!(repo = %self.repo, number = pr_number, "spawning `glab api` POST mr note");
261
262        let encoded_path = encode_project_path(&self.repo);
263        let api_path = format!("/projects/{encoded_path}/merge_requests/{pr_number}/notes");
264        let body_arg = format!("body={body}");
265
266        let output = self
267            .runner
268            .run(
269                "glab",
270                &["api", "--method", "POST", &api_path, "-f", &body_arg],
271            )
272            .await
273            .map_err(|e| CoreError::Platform(format!("Failed to spawn glab api: {e}")))?;
274
275        if !output.status.success() {
276            return Err(parse_glab_error(&output.stderr).into());
277        }
278
279        serde_json::from_slice(&output.stdout).map_err(CoreError::Serialization)
280    }
281
282    /// 获取当前登录用户信息(内部辅助方法)。
283    async fn get_current_user(&self) -> Result<UserSummary> {
284        let output = self
285            .runner
286            .run(
287                "glab",
288                &["mr", "list", "--output", "json", "--per-page", "1"],
289            )
290            .await
291            .map_err(|e| CoreError::Platform(format!("Failed to spawn glab: {e}")))?;
292
293        if !output.status.success() {
294            return Ok(UserSummary {
295                login: "unknown".into(),
296                id: "0".to_string(),
297            });
298        }
299
300        let mrs: Vec<MrViewResponse> =
301            serde_json::from_slice(&output.stdout).map_err(CoreError::Serialization)?;
302
303        if let Some(mr) = mrs.into_iter().next()
304            && let Some(author) = mr.author
305        {
306            return Ok(UserSummary::from(&author));
307        }
308
309        Ok(UserSummary {
310            login: "unknown".into(),
311            id: "0".to_string(),
312        })
313    }
314}
315
316#[cfg(test)]
317mod tests {
318    use super::*;
319    use crate::runner::{MockCommandRunner, SequencedMockCommandRunner};
320
321    #[test]
322    fn test_should_construct_gitlab_review_provider() {
323        let provider = GitLabReviewProvider::new("gitlab-org/gitlab");
324        assert_eq!(provider.repo, "gitlab-org/gitlab");
325    }
326
327    #[test]
328    fn test_should_construct_gitlab_review_provider_from_string() {
329        let repo = String::from("gitlab-org/gitlab");
330        let provider = GitLabReviewProvider::new(repo);
331        assert_eq!(provider.repo, "gitlab-org/gitlab");
332    }
333
334    #[test]
335    fn test_should_deserialize_note_api_response() {
336        let json = br#"{
337            "id": 2001,
338            "body": "Looks great, LGTM!",
339            "author": {"username": "reviewer", "id": 42},
340            "created_at": "2026-05-20T14:30:00Z"
341        }"#;
342
343        let note: NoteApiResponse = serde_json::from_slice(json).expect("valid NoteApiResponse");
344        assert_eq!(note.id, 2001);
345        assert_eq!(note.body, "Looks great, LGTM!");
346        assert_eq!(note.author.as_ref().map(|a| &*a.username), Some("reviewer"));
347    }
348
349    #[test]
350    fn test_should_deserialize_note_without_author() {
351        let json = br#"{
352            "id": 2002,
353            "body": "Anonymous comment",
354            "author": null,
355            "created_at": "2026-05-21T09:00:00Z"
356        }"#;
357
358        let note: NoteApiResponse = serde_json::from_slice(json).expect("valid NoteApiResponse");
359        assert!(note.author.is_none());
360    }
361
362    #[test]
363    fn test_should_convert_note_to_review_data() {
364        let note = NoteApiResponse {
365            id: 100,
366            body: "LGTM".into(),
367            author: Some(ApiUser {
368                username: "reviewer".into(),
369                id: 5,
370            }),
371            created_at: Some("2026-01-01T00:00:00Z".parse().expect("valid date")),
372        };
373
374        let author = note
375            .author
376            .as_ref()
377            .map(UserSummary::from)
378            .expect("has author");
379        let review = ReviewData {
380            id: note.id,
381            state: ReviewState::Commented,
382            body: Some(note.body),
383            author,
384            submitted_at: note.created_at,
385        };
386
387        assert_eq!(review.id, 100);
388        assert_eq!(review.state, ReviewState::Commented);
389        assert_eq!(review.author.login, "reviewer");
390        assert!(review.submitted_at.is_some());
391    }
392
393    #[test]
394    fn test_should_debug_format_provider() {
395        let provider = GitLabReviewProvider::new("gitlab-org/gitlab");
396        let debug = format!("{provider:?}");
397        assert!(debug.contains("GitLabReviewProvider"));
398        assert!(debug.contains("gitlab-org/gitlab"));
399    }
400
401    #[test]
402    fn test_should_clone_gitlab_review_provider() {
403        let original = GitLabReviewProvider::new("owner/repo");
404        let cloned = original.clone();
405        assert_eq!(original.repo, cloned.repo);
406    }
407
408    // --- Failure-path tests using an injected MockCommandRunner ---
409
410    #[tokio::test]
411    async fn test_should_fail_when_review_comment_glab_fails() {
412        let runner = MockCommandRunner::failure(r#"{"message": "Forbidden"}"#, 256);
413        let provider = GitLabReviewProvider::with_runner("owner/repo", runner);
414        let result = provider.comment(7, "fix this").await;
415        assert!(result.is_err());
416    }
417
418    #[tokio::test]
419    async fn test_should_post_review_note_via_glab_api() {
420        let runner = MockCommandRunner::success(
421            r#"{"id":99,"body":"fix this","author":{"username":"alice","id":1},"created_at":"2026-08-18T00:00:00Z"}"#,
422        );
423        let provider = GitLabReviewProvider::with_runner("owner/repo", runner.clone());
424
425        let review = provider.comment(7, "fix this").await.expect("should post");
426
427        assert_eq!(review.id, 99);
428        assert_eq!(review.author.login, "alice");
429        assert_eq!(review.body.as_deref(), Some("fix this"));
430        assert_eq!(
431            runner.recorded_calls()[0].1,
432            vec![
433                "api",
434                "--method",
435                "POST",
436                "/projects/owner%2Frepo/merge_requests/7/notes",
437                "-f",
438                "body=fix this",
439            ]
440            .into_iter()
441            .map(String::from)
442            .collect::<Vec<_>>()
443        );
444    }
445
446    #[tokio::test]
447    async fn test_should_encode_nested_group_repo_path_for_review_note() {
448        let runner = MockCommandRunner::success(
449            r#"{"id":99,"body":"fix this","author":{"username":"alice","id":1},"created_at":"2026-08-18T00:00:00Z"}"#,
450        );
451        let provider = GitLabReviewProvider::with_runner("group/subgroup/project", runner.clone());
452
453        let review = provider.comment(7, "fix this").await.expect("should post");
454
455        assert_eq!(review.id, 99);
456        assert_eq!(
457            runner.recorded_calls()[0].1,
458            vec![
459                "api",
460                "--method",
461                "POST",
462                "/projects/group%2Fsubgroup%2Fproject/merge_requests/7/notes",
463                "-f",
464                "body=fix this",
465            ]
466            .into_iter()
467            .map(String::from)
468            .collect::<Vec<_>>()
469        );
470    }
471
472    #[tokio::test]
473    async fn test_should_request_changes_via_glab_api() {
474        let runner = MockCommandRunner::success(
475            r#"{"id":100,"body":"Changes requested:\n\nredo it","author":{"username":"alice","id":1},"created_at":"2026-08-18T00:00:00Z"}"#,
476        );
477        let provider = GitLabReviewProvider::with_runner("owner/repo", runner.clone());
478
479        let review = provider
480            .request_changes(7, "redo it")
481            .await
482            .expect("should post");
483
484        assert_eq!(review.id, 100);
485        assert_eq!(review.state, ReviewState::ChangesRequested);
486        assert_eq!(
487            review.body.as_deref(),
488            Some("Changes requested:\n\nredo it")
489        );
490        assert_eq!(
491            runner.recorded_calls()[0].1,
492            vec![
493                "api",
494                "--method",
495                "POST",
496                "/projects/owner%2Frepo/merge_requests/7/notes",
497                "-f",
498                "body=Changes requested:\n\nredo it",
499            ]
500            .into_iter()
501            .map(String::from)
502            .collect::<Vec<_>>()
503        );
504    }
505
506    #[test]
507    fn test_should_deserialize_mr_view_response() {
508        let json = br#"{
509            "author": {"username": "maintainer", "id": 99}
510        }"#;
511
512        let mr: MrViewResponse = serde_json::from_slice(json).expect("valid MrViewResponse");
513        assert!(mr.author.is_some());
514        let author = mr.author.as_ref().expect("author present");
515        assert_eq!(author.username, "maintainer");
516        assert_eq!(author.id, 99);
517    }
518
519    #[test]
520    fn test_should_deserialize_mr_view_response_without_author() {
521        let json = br#"{"author": null}"#;
522
523        let mr: MrViewResponse = serde_json::from_slice(json).expect("valid MrViewResponse");
524        assert!(mr.author.is_none());
525    }
526
527    #[test]
528    fn test_should_deserialize_note_without_created_at() {
529        let json = br#"{
530            "id": 3001,
531            "body": "No timestamp",
532            "author": null,
533            "created_at": null
534        }"#;
535
536        let note: NoteApiResponse = serde_json::from_slice(json).expect("valid NoteApiResponse");
537        assert!(note.created_at.is_none());
538        assert!(note.author.is_none());
539    }
540
541    #[test]
542    fn test_should_convert_api_user_to_user_summary() {
543        let user = ApiUser {
544            username: "reviewer".into(),
545            id: 42,
546        };
547        let summary: UserSummary = (&user).into();
548        assert_eq!(summary.login, "reviewer");
549        assert_eq!(summary.id, "42");
550    }
551
552    #[test]
553    fn test_should_convert_api_user_with_zero_id_to_user_summary() {
554        let user = ApiUser {
555            username: "bot".into(),
556            id: 0,
557        };
558        let summary: UserSummary = (&user).into();
559        assert_eq!(summary.login, "bot");
560        assert_eq!(summary.id, "0");
561    }
562
563    // --- approve() tests: --repo dropped, glab auto-detects from git remote ---
564
565    #[tokio::test]
566    async fn test_should_approve_mr_without_repo_flag() {
567        // Sequenced: first `glab mr approve` succeeds, then `glab mr list` (get_current_user).
568        let runner = SequencedMockCommandRunner::from_results(&[
569            (true, "Approved MR #7"),
570            (true, r#"[{"author":{"username":"alice","id":1}}]"#),
571        ]);
572        let provider = GitLabReviewProvider::with_runner("owner/repo", runner.clone());
573
574        let review = provider
575            .approve(7, Some("LGTM"))
576            .await
577            .expect("should approve");
578
579        assert_eq!(review.state, ReviewState::Approved);
580        assert_eq!(review.author.login, "alice");
581
582        let calls = runner.recorded_calls();
583        // First call: `glab mr approve <num> --comment <body>` — NO --repo.
584        assert_eq!(
585            calls[0].1,
586            vec!["mr", "approve", "7", "--comment", "LGTM"]
587                .into_iter()
588                .map(String::from)
589                .collect::<Vec<_>>()
590        );
591        // Second call: `glab mr list --output json --per-page 1` — NO --repo.
592        assert_eq!(
593            calls[1].1,
594            vec!["mr", "list", "--output", "json", "--per-page", "1"]
595                .into_iter()
596                .map(String::from)
597                .collect::<Vec<_>>()
598        );
599    }
600
601    #[tokio::test]
602    async fn test_should_approve_nested_group_mr_without_repo_flag() {
603        // Regression: 3-segment path (iproost/proxy/edge) must NOT pass --repo,
604        // which glab cannot parse. Dropping --repo lets glab auto-detect.
605        let runner = SequencedMockCommandRunner::from_results(&[
606            (true, "Approved MR #26"),
607            (true, r#"[{"author":{"username":"reviewer","id":42}}]"#),
608        ]);
609        let provider = GitLabReviewProvider::with_runner("iproost/proxy/edge", runner.clone());
610
611        let review = provider
612            .approve(26, Some("LGTM"))
613            .await
614            .expect("should approve");
615
616        assert_eq!(review.state, ReviewState::Approved);
617        assert_eq!(review.author.login, "reviewer");
618
619        let calls = runner.recorded_calls();
620        assert_eq!(
621            calls[0].1,
622            vec!["mr", "approve", "26", "--comment", "LGTM"]
623                .into_iter()
624                .map(String::from)
625                .collect::<Vec<_>>()
626        );
627        assert_eq!(
628            calls[1].1,
629            vec!["mr", "list", "--output", "json", "--per-page", "1"]
630                .into_iter()
631                .map(String::from)
632                .collect::<Vec<_>>()
633        );
634    }
635}