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