Skip to main content

gitflow_core/
pr.rs

1//! Pull Request 领域类型与平台抽象。
2//!
3//! 定义了 PR 的数据表示、创建/列表参数,以及跨平台实现所需的
4//! [`PrProvider`] trait。GitHub、GitLab、GitCode 等平台实现都
5//! 需实现该 trait,使上层命令层可统一消费。
6
7use async_trait::async_trait;
8use chrono::{DateTime, Utc};
9use serde::{Deserialize, Serialize};
10
11use crate::{
12    Result,
13    types::{
14        CommentData, MergeResult, MergeStrategy, State, UserSummary, deserialize_u64_or_string,
15    },
16};
17
18/// Pull Request 数据。
19///
20/// 由平台实现填充并返回给上层命令。字段命名与 `gh pr`
21/// CLI 输出的 JSON 字段对齐(camelCase)。
22#[derive(Debug, Clone, Serialize, Deserialize)]
23#[serde(rename_all = "camelCase")]
24pub struct PrData {
25    /// PR 编号(平台内唯一)。
26    #[serde(deserialize_with = "deserialize_u64_or_string")]
27    pub number: u64,
28    /// PR 标题。
29    pub title: String,
30    /// PR 正文(Markdown)。
31    #[serde(skip_serializing_if = "Option::is_none")]
32    pub body: Option<String>,
33    /// PR 当前状态。
34    pub state: State,
35    /// 是否为草稿 PR。
36    #[serde(alias = "isDraft")]
37    pub draft: bool,
38    /// PR 作者。
39    pub author: UserSummary,
40    /// 目标分支。
41    #[serde(alias = "baseRefName")]
42    pub base_branch: String,
43    /// 来源分支。
44    #[serde(alias = "headRefName")]
45    pub head_branch: String,
46    /// 创建时间(UTC)。
47    pub created_at: DateTime<Utc>,
48    /// 最近更新时间(UTC)。
49    pub updated_at: DateTime<Utc>,
50    /// PR 的 Web URL。
51    pub url: String,
52}
53
54/// 创建 PR 所需参数。
55#[derive(Debug, Clone)]
56pub struct CreatePrArgs {
57    /// PR 标题。
58    pub title: String,
59    /// PR 正文(可选)。
60    pub body: Option<String>,
61    /// 来源分支。
62    pub head: String,
63    /// 目标分支。
64    pub base: String,
65    /// 是否以草稿方式创建。
66    pub draft: bool,
67    /// 可选的目标仓库(`owner/name` 格式),未设置时使用默认仓库。
68    pub repo: Option<String>,
69}
70
71/// 列出 PR 的过滤参数。
72///
73/// 所有字段均可选,未设置时使用平台默认值。
74#[derive(Debug, Clone, Default)]
75pub struct ListPrArgs {
76    /// 按状态过滤。
77    pub state: Option<State>,
78    /// 返回数量上限。
79    pub limit: Option<u32>,
80}
81
82/// PR 操作的平台抽象。
83///
84/// 所有平台实现(GitHub/GitLab/GitCode)都必须实现此 trait,
85/// 以提供统一的 PR 创建、列表、查看、关闭、合并、检出等能力。
86///
87/// # Errors
88///
89/// 所有方法在平台调用失败、反序列化失败或鉴权失败时返回 [`CoreError`](crate::CoreError)。
90///
91/// [`CoreError`]: crate::CoreError
92#[async_trait]
93pub trait PrProvider: std::fmt::Debug + Send + Sync {
94    /// 创建一条新 PR,返回平台生成的完整数据。
95    ///
96    /// # Errors
97    ///
98    /// 当平台 API 调用失败或参数非法时返回错误。
99    async fn create(&self, args: CreatePrArgs) -> Result<PrData>;
100
101    /// 根据过滤条件列出 PR 列表。
102    ///
103    /// # Errors
104    ///
105    /// 当平台 API 调用失败或过滤条件非法时返回错误。
106    async fn list(&self, args: ListPrArgs) -> Result<Vec<PrData>>;
107
108    /// 查看指定编号的 PR 详情。
109    ///
110    /// # Errors
111    ///
112    /// 当 PR 不存在或平台 API 调用失败时返回错误。
113    async fn view(&self, number: u64) -> Result<PrData>;
114
115    /// 关闭指定编号的 PR,返回更新后的数据。
116    ///
117    /// # Errors
118    ///
119    /// 当 PR 不存在或平台 API 调用失败时返回错误。
120    async fn close(&self, number: u64) -> Result<PrData>;
121
122    /// 重新打开指定编号的 PR,返回更新后的数据。
123    ///
124    /// # Errors
125    ///
126    /// 当 PR 不存在或平台 API 调用失败时返回错误。
127    async fn reopen(&self, number: u64) -> Result<PrData>;
128
129    /// 在指定 PR 上添加评论,返回新建评论的数据。
130    ///
131    /// # Errors
132    ///
133    /// 当 PR 不存在、`body` 为空或平台 API 调用失败时返回错误。
134    async fn comment(&self, number: u64, body: &str) -> Result<CommentData>;
135
136    /// 合并指定编号的 PR,返回合并结果。
137    ///
138    /// `strategy` 指定合并策略(merge/squash/rebase)。
139    /// 未指定时使用平台默认策略。
140    ///
141    /// # Errors
142    ///
143    /// 当 PR 不存在、无法合并或平台 API 调用失败时返回错误。
144    async fn merge(&self, number: u64, strategy: Option<MergeStrategy>) -> Result<MergeResult>;
145
146    /// 在本地检出指定 PR 的分支。
147    ///
148    /// # Errors
149    ///
150    /// 当 PR 不存在或 git 操作失败时返回错误。
151    async fn checkout(&self, number: u64) -> Result<()>;
152
153    /// 将草稿 PR 标记为可审查状态(ready for review)。
154    ///
155    /// # Errors
156    ///
157    /// 当 PR 不存在、不是草稿或平台 API 调用失败时返回错误。
158    async fn mark_ready(&self, number: u64) -> Result<PrData>;
159
160    /// 将 PR 标记为草稿状态(work in progress)。
161    ///
162    /// # Errors
163    ///
164    /// 当 PR 不存在或平台 API 调用失败时返回错误。
165    async fn mark_wip(&self, number: u64) -> Result<PrData>;
166
167    /// 同步 PR 分支(将 base 分支的最新变更合入 head 分支)。
168    ///
169    /// # Errors
170    ///
171    /// 当 PR 不存在或同步失败时返回错误。
172    async fn sync_branch(&self, number: u64) -> Result<()>;
173}
174
175#[cfg(test)]
176mod tests {
177    use super::*;
178
179    /// 构造用于 serde 测试的样本 JSON,字段命名与 `gh pr view --json` 输出一致。
180    fn sample_pr_json() -> &'static str {
181        r#"{
182            "number": 101,
183            "title": "Add feature X",
184            "body": "Implements X per spec.",
185            "state": "open",
186            "draft": false,
187            "author": {"login": "alice", "id": "7"},
188            "baseBranch": "main",
189            "headBranch": "feature/x",
190            "createdAt": "2026-02-10T08:00:00Z",
191            "updatedAt": "2026-02-11T12:30:00Z",
192            "url": "https://github.com/octocat/hello-world/pull/101"
193        }"#
194    }
195
196    #[test]
197    fn test_should_deserialize_pr_data_from_gh_cli_json() {
198        let json = sample_pr_json();
199        let pr: PrData = serde_json::from_str(json).expect("valid PrData JSON");
200
201        assert_eq!(pr.number, 101);
202        assert_eq!(pr.title, "Add feature X");
203        assert_eq!(pr.body.as_deref(), Some("Implements X per spec."));
204        assert_eq!(pr.state, State::Open);
205        assert!(!pr.draft);
206        assert_eq!(pr.author.login, "alice");
207        assert_eq!(pr.author.id, "7");
208        assert_eq!(pr.base_branch, "main");
209        assert_eq!(pr.head_branch, "feature/x");
210        assert_eq!(pr.url, "https://github.com/octocat/hello-world/pull/101");
211    }
212
213    #[test]
214    fn test_should_roundtrip_pr_data_via_serde() {
215        let json = sample_pr_json();
216        let pr: PrData = serde_json::from_str(json).expect("deserialize");
217        let re_serialized = serde_json::to_string(&pr).expect("serialize");
218        let round_tripped: PrData = serde_json::from_str(&re_serialized).expect("re-deserialize");
219
220        assert_eq!(round_tripped.number, pr.number);
221        assert_eq!(round_tripped.title, pr.title);
222        assert_eq!(round_tripped.body, pr.body);
223        assert_eq!(round_tripped.state, pr.state);
224        assert_eq!(round_tripped.draft, pr.draft);
225        assert_eq!(round_tripped.base_branch, pr.base_branch);
226        assert_eq!(round_tripped.head_branch, pr.head_branch);
227        assert_eq!(round_tripped.url, pr.url);
228        assert_eq!(round_tripped.created_at, pr.created_at);
229        assert_eq!(round_tripped.updated_at, pr.updated_at);
230    }
231
232    #[test]
233    fn test_should_deserialize_draft_pr_with_null_body() {
234        let json = r#"{
235            "number": 5,
236            "title": "WIP experiment",
237            "body": null,
238            "state": "open",
239            "draft": true,
240            "author": {"login": "bob", "id": "9"},
241            "baseBranch": "main",
242            "headBranch": "wip",
243            "createdAt": "2026-04-01T00:00:00Z",
244            "updatedAt": "2026-04-02T00:00:00Z",
245            "url": "https://example.com/pull/5"
246        }"#;
247        let pr: PrData = serde_json::from_str(json).expect("deserialize");
248        assert!(pr.draft);
249        assert!(pr.body.is_none());
250        assert_eq!(pr.state, State::Open);
251    }
252
253    #[test]
254    fn test_should_omit_none_body_on_serialize() {
255        let json = sample_pr_json();
256        let mut pr: PrData = serde_json::from_str(json).expect("deserialize");
257        pr.body = None;
258        let serialized = serde_json::to_string(&pr).expect("serialize");
259        // `body: null` 不应出现在输出中
260        assert!(!serialized.contains("\"body\":null"));
261        assert!(!serialized.contains("\"body\": null"));
262    }
263
264    #[test]
265    fn test_should_serialize_camel_case_fields() {
266        let json = sample_pr_json();
267        let pr: PrData = serde_json::from_str(json).expect("deserialize");
268        let serialized = serde_json::to_string(&pr).expect("serialize");
269        // camelCase 字段必须被保留
270        assert!(serialized.contains("\"baseBranch\""));
271        assert!(serialized.contains("\"headBranch\""));
272        assert!(serialized.contains("\"createdAt\""));
273        assert!(serialized.contains("\"updatedAt\""));
274        // snake_case 字段不应出现
275        assert!(!serialized.contains("\"base_branch\""));
276        assert!(!serialized.contains("\"head_branch\""));
277    }
278
279    #[test]
280    fn test_list_pr_args_default_is_empty() {
281        let args = ListPrArgs::default();
282        assert!(args.state.is_none());
283        assert!(args.limit.is_none());
284    }
285}