Skip to main content

gitflow_core/
review.rs

1//! Review 领域类型与平台抽象。
2//!
3//! 定义了 Code Review 的数据表示、状态枚举、评论数据,以及
4//! 跨平台实现所需的 [`ReviewProvider`] trait。GitHub、GitLab、
5//! `GitCode` 等平台实现都需实现该 trait,使上层命令层可统一消费。
6
7use async_trait::async_trait;
8use chrono::{DateTime, Utc};
9use serde::{Deserialize, Serialize};
10
11use crate::{Result, types::UserSummary};
12
13/// Review 状态枚举。
14///
15/// 表示一次代码审查的最终结论。
16///
17/// 使用 `snake_case` 进行序列化,并提供 UPPERCASE 别名
18/// 以兼容 GitHub `gh` CLI 的输出格式。
19#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
20#[serde(rename_all = "snake_case")]
21pub enum ReviewState {
22    /// 审查通过,可以合并。
23    #[serde(alias = "APPROVED")]
24    Approved,
25    /// 要求修改后才能合并。
26    #[serde(alias = "CHANGES_REQUESTED")]
27    ChangesRequested,
28    /// 仅发表评论,不表态。
29    #[serde(alias = "COMMENTED")]
30    Commented,
31}
32
33/// Review 数据。
34///
35/// 由平台实现填充并返回给上层命令。字段命名与
36/// `gh pr review` CLI 输出的 JSON 字段对齐(camelCase)。
37#[derive(Debug, Clone, Serialize, Deserialize)]
38#[serde(rename_all = "camelCase")]
39pub struct ReviewData {
40    /// Review 的 numeric ID。
41    pub id: u64,
42    /// Review 的最终状态。
43    pub state: ReviewState,
44    /// Review 正文(Markdown,可选)。
45    #[serde(skip_serializing_if = "Option::is_none")]
46    pub body: Option<String>,
47    /// 审查人。
48    pub author: UserSummary,
49    /// 提交时间(UTC)。
50    pub submitted_at: DateTime<Utc>,
51}
52
53/// Review 评论数据。
54///
55/// 表示单条行内或文件级别的代码审查评论。
56#[derive(Debug, Clone, Serialize, Deserialize)]
57#[serde(rename_all = "camelCase")]
58pub struct ReviewCommentData {
59    /// 评论的 numeric ID。
60    pub id: u64,
61    /// 被评论的文件路径(行内评论时有值)。
62    #[serde(skip_serializing_if = "Option::is_none")]
63    pub path: Option<String>,
64    /// 评论正文。
65    pub body: String,
66    /// 被评论的行号(行内评论时有值)。
67    #[serde(skip_serializing_if = "Option::is_none")]
68    pub line: Option<u32>,
69    /// 被评论的代码块差异(hunk)。
70    #[serde(skip_serializing_if = "Option::is_none")]
71    pub diff_hunk: Option<String>,
72    /// 评论作者。
73    pub author: UserSummary,
74    /// 创建时间(UTC)。
75    pub created_at: DateTime<Utc>,
76}
77
78/// Review 操作的平台抽象。
79///
80/// 所有平台实现(GitHub/GitLab/GitCode)都必须实现此 trait,
81/// 以提供统一的代码审查评论、批准、要求修改及提交审查能力。
82///
83/// # Errors
84///
85/// 所有方法在平台调用失败、反序列化失败或鉴权失败时返回
86/// [`CoreError`](crate::CoreError)。
87///
88/// [`CoreError`]: crate::CoreError
89#[async_trait]
90pub trait ReviewProvider: std::fmt::Debug + Send + Sync {
91    /// 在指定 PR 上发表评论。
92    ///
93    /// # Errors
94    ///
95    /// 当 PR 不存在、`body` 为空或平台 API 调用失败时返回错误。
96    async fn comment(&self, pr_number: u64, body: &str) -> Result<ReviewData>;
97
98    /// 批准指定 PR。
99    ///
100    /// `body` 为可选的批准说明。
101    ///
102    /// # Errors
103    ///
104    /// 当 PR 不存在或平台 API 调用失败时返回错误。
105    async fn approve(&self, pr_number: u64, body: Option<&str>) -> Result<ReviewData>;
106
107    /// 要求对指定 PR 进行修改。
108    ///
109    /// `body` 为修改要求的说明。
110    ///
111    /// # Errors
112    ///
113    /// 当 PR 不存在或平台 API 调用失败时返回错误。
114    async fn request_changes(&self, pr_number: u64, body: &str) -> Result<ReviewData>;
115
116    /// 提交一次完整的 Review。
117    ///
118    /// `event` 指定提交的最终结论(批准/要求修改/仅评论),
119    /// `body` 为可选的总结说明。
120    ///
121    /// # Errors
122    ///
123    /// 当 PR 不存在或平台 API 调用失败时返回错误。
124    async fn submit_review(
125        &self,
126        pr_number: u64,
127        event: ReviewState,
128        body: Option<&str>,
129    ) -> Result<ReviewData>;
130}
131
132#[cfg(test)]
133mod tests {
134    use super::*;
135
136    fn sample_review_json() -> &'static str {
137        r#"{
138            "id": 2001,
139            "state": "approved",
140            "body": "Looks great, LGTM!",
141            "author": {"login": "reviewer", "id": "42"},
142            "submittedAt": "2026-05-20T14:30:00Z"
143        }"#
144    }
145
146    fn sample_review_comment_json() -> &'static str {
147        r#"{
148            "id": 3001,
149            "path": "src/main.rs",
150            "body": "Consider using `Result` here",
151            "line": 42,
152            "diffHunk": "@@ -40,3 +40,5 @@ fn main()",
153            "author": {"login": "alice", "id": "7"},
154            "createdAt": "2026-05-19T10:00:00Z"
155        }"#
156    }
157
158    #[test]
159    fn test_should_deserialize_review_data_from_json() {
160        let json = sample_review_json();
161        let review: ReviewData = serde_json::from_str(json).expect("valid ReviewData JSON");
162
163        assert_eq!(review.id, 2001);
164        assert_eq!(review.state, ReviewState::Approved);
165        assert_eq!(review.body.as_deref(), Some("Looks great, LGTM!"));
166        assert_eq!(review.author.login, "reviewer");
167        assert_eq!(review.author.id, "42");
168    }
169
170    #[test]
171    fn test_should_roundtrip_review_data_via_serde() {
172        let json = sample_review_json();
173        let review: ReviewData = serde_json::from_str(json).expect("deserialize");
174        let re_serialized = serde_json::to_string(&review).expect("serialize");
175        let round_tripped: ReviewData =
176            serde_json::from_str(&re_serialized).expect("re-deserialize");
177
178        assert_eq!(round_tripped.id, review.id);
179        assert_eq!(round_tripped.state, review.state);
180        assert_eq!(round_tripped.body, review.body);
181        assert_eq!(round_tripped.author.login, review.author.login);
182        assert_eq!(round_tripped.submitted_at, review.submitted_at);
183    }
184
185    #[test]
186    fn test_should_deserialize_review_comment_data_from_json() {
187        let json = sample_review_comment_json();
188        let comment: ReviewCommentData =
189            serde_json::from_str(json).expect("valid ReviewCommentData JSON");
190
191        assert_eq!(comment.id, 3001);
192        assert_eq!(comment.path.as_deref(), Some("src/main.rs"));
193        assert_eq!(comment.body, "Consider using `Result` here");
194        assert_eq!(comment.line, Some(42));
195        assert_eq!(
196            comment.diff_hunk.as_deref(),
197            Some("@@ -40,3 +40,5 @@ fn main()")
198        );
199        assert_eq!(comment.author.login, "alice");
200        assert_eq!(comment.author.id, "7");
201    }
202
203    #[test]
204    fn test_should_roundtrip_review_comment_data_via_serde() {
205        let json = sample_review_comment_json();
206        let comment: ReviewCommentData = serde_json::from_str(json).expect("deserialize");
207        let re_serialized = serde_json::to_string(&comment).expect("serialize");
208        let round_tripped: ReviewCommentData =
209            serde_json::from_str(&re_serialized).expect("re-deserialize");
210
211        assert_eq!(round_tripped.id, comment.id);
212        assert_eq!(round_tripped.path, comment.path);
213        assert_eq!(round_tripped.body, comment.body);
214        assert_eq!(round_tripped.line, comment.line);
215        assert_eq!(round_tripped.diff_hunk, comment.diff_hunk);
216        assert_eq!(round_tripped.author.login, comment.author.login);
217        assert_eq!(round_tripped.author.id, comment.author.id);
218        assert_eq!(round_tripped.created_at, comment.created_at);
219    }
220
221    #[test]
222    fn test_should_serialize_review_comment_skips_null_fields() {
223        let comment = ReviewCommentData {
224            id: 1,
225            path: None,
226            body: "file-level comment".into(),
227            line: None,
228            diff_hunk: None,
229            author: UserSummary {
230                login: "bob".into(),
231                id: "3".to_string(),
232            },
233            created_at: "2026-01-01T00:00:00Z".parse().expect("valid date"),
234        };
235        let json = serde_json::to_string(&comment).expect("serialize");
236        assert!(!json.contains("null"));
237        assert!(!json.contains("\"path\":"));
238        assert!(!json.contains("\"line\":"));
239        assert!(!json.contains("\"diffHunk\":"));
240        assert!(json.contains("\"body\":\"file-level comment\""));
241    }
242
243    #[test]
244    fn test_should_serialize_review_state_to_snake_case() {
245        let json = serde_json::to_string(&ReviewState::Approved).expect("serialize");
246        assert_eq!(json, "\"approved\"");
247
248        let json = serde_json::to_string(&ReviewState::ChangesRequested).expect("serialize");
249        assert_eq!(json, "\"changes_requested\"");
250
251        let json = serde_json::to_string(&ReviewState::Commented).expect("serialize");
252        assert_eq!(json, "\"commented\"");
253    }
254
255    #[test]
256    fn test_should_deserialize_review_state_from_snake_case() {
257        let state: ReviewState = serde_json::from_str("\"approved\"").expect("deserialize");
258        assert_eq!(state, ReviewState::Approved);
259
260        let state: ReviewState =
261            serde_json::from_str("\"changes_requested\"").expect("deserialize");
262        assert_eq!(state, ReviewState::ChangesRequested);
263
264        let state: ReviewState = serde_json::from_str("\"commented\"").expect("deserialize");
265        assert_eq!(state, ReviewState::Commented);
266    }
267
268    #[test]
269    fn test_should_deserialize_review_state_from_github_uppercase() {
270        let state: ReviewState = serde_json::from_str("\"APPROVED\"").expect("deserialize");
271        assert_eq!(state, ReviewState::Approved);
272
273        let state: ReviewState =
274            serde_json::from_str("\"CHANGES_REQUESTED\"").expect("deserialize");
275        assert_eq!(state, ReviewState::ChangesRequested);
276
277        let state: ReviewState = serde_json::from_str("\"COMMENTED\"").expect("deserialize");
278        assert_eq!(state, ReviewState::Commented);
279    }
280
281    #[test]
282    fn test_should_derive_clone_and_copy_for_review_state() {
283        let state = ReviewState::Approved;
284        let cloned = state;
285        let copied = state;
286        assert_eq!(state, cloned);
287        assert_eq!(state, copied);
288    }
289
290    #[test]
291    fn test_should_derive_debug_for_review_state() {
292        let debug = format!("{:?}", ReviewState::ChangesRequested);
293        assert_eq!(debug, "ChangesRequested");
294    }
295
296    #[test]
297    fn test_should_derive_eq_for_review_state() {
298        assert_eq!(ReviewState::Approved, ReviewState::Approved);
299        assert_ne!(ReviewState::Approved, ReviewState::ChangesRequested);
300    }
301
302    #[test]
303    fn test_should_deserialize_review_data_with_null_body() {
304        let json = r#"{
305            "id": 10,
306            "state": "commented",
307            "body": null,
308            "author": {"login": "u", "id": "1"},
309            "submittedAt": "2026-06-01T00:00:00Z"
310        }"#;
311        let review: ReviewData = serde_json::from_str(json).expect("deserialize");
312        assert_eq!(review.state, ReviewState::Commented);
313        assert!(review.body.is_none());
314    }
315}