Skip to main content

gitflow_core/
release.rs

1//! Release 领域类型与平台抽象。
2//!
3//! 定义了 Release(版本发布)的数据表示、创建参数,以及跨平台
4//! 实现所需的 [`ReleaseProvider`] trait。GitHub、GitLab、GitCode
5//! 等平台实现都需实现该 trait,使上层命令层可统一消费。
6
7use async_trait::async_trait;
8use chrono::{DateTime, Utc};
9use serde::{Deserialize, Serialize};
10
11use crate::{Result, types::UserSummary};
12
13/// Release 数据。
14///
15/// 由平台实现填充并返回给上层命令。字段命名与 `gh release`
16/// CLI 输出的 JSON 字段对齐(camelCase)。
17#[derive(Debug, Clone, Serialize, Deserialize)]
18#[serde(rename_all = "camelCase")]
19pub struct ReleaseData {
20    /// Release 的 numeric ID(list 命令可能不包含此字段)。
21    #[serde(default, alias = "databaseId")]
22    pub id: u64,
23    /// 关联的 Git tag 名。
24    pub tag_name: String,
25    /// Release 标题(可选)。
26    #[serde(skip_serializing_if = "Option::is_none")]
27    pub name: Option<String>,
28    /// Release 正文(Markdown,list 命令可能不包含此字段)。
29    #[serde(skip_serializing_if = "Option::is_none")]
30    pub body: Option<String>,
31    /// 是否为草稿 Release。
32    #[serde(alias = "isDraft")]
33    pub draft: bool,
34    /// 是否为预发布版本。
35    #[serde(alias = "isPrerelease")]
36    pub prerelease: bool,
37    /// Release 作者(list 命令可能不包含此字段)。
38    #[serde(skip_serializing_if = "Option::is_none")]
39    pub author: Option<UserSummary>,
40    /// 创建时间(UTC)。
41    pub created_at: DateTime<Utc>,
42    /// 发布时间(UTC),草稿 Release 为 None。
43    #[serde(skip_serializing_if = "Option::is_none")]
44    pub published_at: Option<DateTime<Utc>>,
45    /// Release 的 Web URL(list 命令可能不包含此字段)。
46    #[serde(default)]
47    pub url: String,
48}
49
50/// 创建 Release 所需参数。
51#[derive(Debug, Clone)]
52pub struct CreateReleaseArgs {
53    /// 关联的 Git tag 名。
54    pub tag_name: String,
55    /// Release 标题(可选)。
56    pub name: Option<String>,
57    /// Release 正文(Markdown)。
58    pub body: Option<String>,
59    /// 是否以草稿方式创建。
60    pub draft: bool,
61    /// 是否为预发布版本。
62    pub prerelease: bool,
63    /// 目标 commitish(可选,默认当前分支 HEAD)。
64    pub target_commitish: Option<String>,
65}
66
67/// Release 操作的平台抽象。
68///
69/// 所有平台实现(GitHub/GitLab/GitCode)都必须实现此 trait,
70/// 以提供统一的 Release 创建、列表、查看、编辑、资源上传/下载
71/// 及删除能力。
72///
73/// # Errors
74///
75/// 所有方法在平台调用失败、反序列化失败或鉴权失败时返回
76/// [`CoreError`](crate::CoreError)。
77///
78/// [`CoreError`]: crate::CoreError
79#[async_trait]
80pub trait ReleaseProvider: std::fmt::Debug + Send + Sync {
81    /// 创建一条新 Release,返回平台生成的完整数据。
82    ///
83    /// # Errors
84    ///
85    /// 当平台 API 调用失败或参数非法时返回错误。
86    async fn create(&self, args: CreateReleaseArgs) -> Result<ReleaseData>;
87
88    /// 列出仓库的 Release 列表。
89    ///
90    /// # Errors
91    ///
92    /// 当平台 API 调用失败时返回错误。
93    async fn list(&self) -> Result<Vec<ReleaseData>>;
94
95    /// 查看指定 tag 的 Release 详情。
96    ///
97    /// # Errors
98    ///
99    /// 当 Release 不存在或平台 API 调用失败时返回错误。
100    async fn view(&self, tag_name: &str) -> Result<ReleaseData>;
101
102    /// 编辑指定 Release 的元数据,返回更新后的数据。
103    ///
104    /// # Errors
105    ///
106    /// 当 Release 不存在或平台 API 调用失败时返回错误。
107    async fn edit(&self, tag_name: &str, args: CreateReleaseArgs) -> Result<ReleaseData>;
108
109    /// 上传资源文件到指定 Release。
110    ///
111    /// `file_path` 为本地文件路径,`asset_name` 为在 Release
112    /// 中显示的资源名。
113    ///
114    /// # Errors
115    ///
116    /// 当 Release 不存在、文件读取失败或平台 API 调用失败时返回错误。
117    async fn upload_asset(&self, tag_name: &str, file_path: &str, asset_name: &str) -> Result<()>;
118
119    /// 下载指定 Release 的资源文件到本地路径。
120    ///
121    /// # Errors
122    ///
123    /// 当 Release 不存在、资源不存在或写入失败时返回错误。
124    async fn download_asset(&self, tag_name: &str, asset_name: &str, dest_path: &str)
125    -> Result<()>;
126
127    /// 删除指定 Release。
128    ///
129    /// # Errors
130    ///
131    /// 当 Release 不存在或平台 API 调用失败时返回错误。
132    async fn delete(&self, tag_name: &str) -> Result<()>;
133}
134
135#[cfg(test)]
136mod tests {
137    use super::*;
138
139    fn sample_release_json() -> &'static str {
140        r#"{
141            "id": 1001,
142            "tagName": "v1.0.0",
143            "name": "Version 1.0.0",
144            "body": "Initial stable release",
145            "draft": false,
146            "prerelease": false,
147            "author": {"login": "octocat", "id": "1"},
148            "createdAt": "2026-01-01T00:00:00Z",
149            "publishedAt": "2026-01-15T12:00:00Z",
150            "url": "https://github.com/octocat/hello-world/releases/tag/v1.0.0"
151        }"#
152    }
153
154    #[test]
155    fn test_should_deserialize_release_data_from_json() {
156        let json = sample_release_json();
157        let release: ReleaseData = serde_json::from_str(json).expect("valid ReleaseData JSON");
158
159        assert_eq!(release.id, 1001);
160        assert_eq!(release.tag_name, "v1.0.0");
161        assert_eq!(release.name.as_deref(), Some("Version 1.0.0"));
162        assert_eq!(release.body.as_deref(), Some("Initial stable release"));
163        assert!(!release.draft);
164        assert!(!release.prerelease);
165        assert_eq!(release.author.as_ref().unwrap().login, "octocat");
166        assert_eq!(release.author.as_ref().unwrap().id, "1");
167        assert_eq!(
168            release.url,
169            "https://github.com/octocat/hello-world/releases/tag/v1.0.0"
170        );
171    }
172
173    #[test]
174    fn test_should_roundtrip_release_data_via_serde() {
175        let json = sample_release_json();
176        let release: ReleaseData = serde_json::from_str(json).expect("deserialize");
177        let re_serialized = serde_json::to_string(&release).expect("serialize");
178        let round_tripped: ReleaseData =
179            serde_json::from_str(&re_serialized).expect("re-deserialize");
180
181        assert_eq!(round_tripped.id, release.id);
182        assert_eq!(round_tripped.tag_name, release.tag_name);
183        assert_eq!(round_tripped.name, release.name);
184        assert_eq!(round_tripped.body, release.body);
185        assert_eq!(round_tripped.draft, release.draft);
186        assert_eq!(round_tripped.prerelease, release.prerelease);
187        assert_eq!(round_tripped.created_at, release.created_at);
188        assert_eq!(round_tripped.published_at, release.published_at);
189        assert_eq!(round_tripped.url, release.url);
190    }
191
192    #[test]
193    fn test_should_deserialize_draft_release_with_null_optional_fields() {
194        let json = r#"{
195            "id": 5,
196            "tagName": "v0.1.0-draft",
197            "name": null,
198            "body": null,
199            "draft": true,
200            "prerelease": true,
201            "author": {"login": "dev", "id": "99"},
202            "createdAt": "2026-03-01T00:00:00Z",
203            "publishedAt": null,
204            "url": "https://example.com/releases/5"
205        }"#;
206        let release: ReleaseData = serde_json::from_str(json).expect("deserialize");
207        assert!(release.draft);
208        assert!(release.prerelease);
209        assert!(release.name.is_none());
210        assert!(release.body.is_none());
211        assert!(release.published_at.is_none());
212    }
213
214    #[test]
215    fn test_should_omit_none_fields_on_serialize() {
216        let json = sample_release_json();
217        let mut release: ReleaseData = serde_json::from_str(json).expect("deserialize");
218        release.name = None;
219        release.body = None;
220        release.published_at = None;
221        let serialized = serde_json::to_string(&release).expect("serialize");
222        assert!(!serialized.contains("null"));
223        assert!(!serialized.contains("\"name\":"));
224        assert!(!serialized.contains("\"body\":"));
225        assert!(!serialized.contains("\"publishedAt\":"));
226    }
227
228    #[test]
229    fn test_should_serialize_camel_case_fields() {
230        let json = sample_release_json();
231        let release: ReleaseData = serde_json::from_str(json).expect("deserialize");
232        let serialized = serde_json::to_string(&release).expect("serialize");
233        assert!(serialized.contains("\"tagName\""));
234        assert!(serialized.contains("\"createdAt\""));
235        assert!(serialized.contains("\"publishedAt\""));
236        assert!(!serialized.contains("\"tag_name\""));
237        assert!(!serialized.contains("\"created_at\""));
238        assert!(!serialized.contains("\"published_at\""));
239    }
240
241    #[test]
242    fn test_create_release_args_debug_derive() {
243        let args = CreateReleaseArgs {
244            tag_name: "v1.0.0".into(),
245            name: Some("v1".into()),
246            body: None,
247            draft: false,
248            prerelease: false,
249            target_commitish: Some("abc123".into()),
250        };
251        let debug = format!("{args:?}");
252        assert!(debug.contains("CreateReleaseArgs"));
253        assert!(debug.contains("v1.0.0"));
254    }
255
256    // --- Alias deserialization tests ---
257
258    #[test]
259    fn test_should_deserialize_is_draft_alias() {
260        let json = r#"{
261            "id": 1,
262            "tagName": "v0.1.0",
263            "isDraft": true,
264            "prerelease": false,
265            "createdAt": "2026-01-01T00:00:00Z"
266        }"#;
267        let release: ReleaseData = serde_json::from_str(json).expect("deserialize");
268        assert!(release.draft);
269        assert!(!release.prerelease);
270    }
271
272    #[test]
273    fn test_should_deserialize_is_prerelease_alias() {
274        let json = r#"{
275            "id": 1,
276            "tagName": "v0.1.0",
277            "draft": false,
278            "isPrerelease": true,
279            "createdAt": "2026-01-01T00:00:00Z"
280        }"#;
281        let release: ReleaseData = serde_json::from_str(json).expect("deserialize");
282        assert!(!release.draft);
283        assert!(release.prerelease);
284    }
285
286    #[test]
287    fn test_should_deserialize_database_id_alias() {
288        let json = r#"{
289            "databaseId": 42,
290            "tagName": "v1.0.0",
291            "draft": false,
292            "prerelease": false,
293            "createdAt": "2026-01-01T00:00:00Z"
294        }"#;
295        let release: ReleaseData = serde_json::from_str(json).expect("deserialize");
296        assert_eq!(release.id, 42);
297    }
298
299    #[test]
300    fn test_should_reject_duplicate_id_and_database_id() {
301        let json = r#"{
302            "id": 10,
303            "databaseId": 99,
304            "tagName": "v1.0.0",
305            "draft": false,
306            "prerelease": false,
307            "createdAt": "2026-01-01T00:00:00Z"
308        }"#;
309        let result: std::result::Result<ReleaseData, _> = serde_json::from_str(json);
310        // Serde rejects duplicate fields when both the primary name and an alias
311        // are present in the same JSON object.
312        assert!(result.is_err());
313    }
314
315    // --- Default / optional field tests ---
316
317    #[test]
318    fn test_should_default_url_to_empty_string() {
319        let json = r#"{
320            "id": 1,
321            "tagName": "v0.1.0",
322            "draft": false,
323            "prerelease": false,
324            "createdAt": "2026-01-01T00:00:00Z"
325        }"#;
326        let release: ReleaseData = serde_json::from_str(json).expect("deserialize");
327        assert_eq!(release.url, "");
328    }
329
330    #[test]
331    fn test_should_default_id_to_zero() {
332        let json = r#"{
333            "tagName": "v0.1.0",
334            "draft": false,
335            "prerelease": false,
336            "createdAt": "2026-01-01T00:00:00Z"
337        }"#;
338        let release: ReleaseData = serde_json::from_str(json).expect("deserialize");
339        assert_eq!(release.id, 0);
340    }
341
342    // --- Skip-serializing-if tests for optional fields ---
343
344    #[test]
345    fn test_should_skip_author_when_none_on_serialize() {
346        let json = r#"{
347            "id": 1,
348            "tagName": "v1.0.0",
349            "draft": false,
350            "prerelease": false,
351            "createdAt": "2026-01-01T00:00:00Z",
352            "url": ""
353        }"#;
354        let release: ReleaseData = serde_json::from_str(json).expect("deserialize");
355        assert!(release.author.is_none());
356        let serialized = serde_json::to_string(&release).expect("serialize");
357        assert!(!serialized.contains("\"author\""));
358    }
359
360    // --- Debug format tests ---
361
362    #[test]
363    fn test_release_data_should_have_debug_format() {
364        let json = sample_release_json();
365        let release: ReleaseData = serde_json::from_str(json).expect("deserialize");
366        let debug = format!("{release:?}");
367        assert!(debug.contains("ReleaseData"));
368        assert!(debug.contains("v1.0.0"));
369        assert!(debug.contains("Version 1.0.0"));
370    }
371
372    // --- CreateReleaseArgs additional tests ---
373
374    #[test]
375    fn test_should_create_release_args_with_minimal_fields() {
376        let args = CreateReleaseArgs {
377            tag_name: "v1.0.0".into(),
378            name: None,
379            body: None,
380            draft: false,
381            prerelease: false,
382            target_commitish: None,
383        };
384        assert_eq!(args.tag_name, "v1.0.0");
385        assert!(args.name.is_none());
386        assert!(args.body.is_none());
387        assert!(!args.draft);
388        assert!(!args.prerelease);
389        assert!(args.target_commitish.is_none());
390    }
391
392    #[test]
393    fn test_should_create_release_args_with_all_fields() {
394        let args = CreateReleaseArgs {
395            tag_name: "v2.0.0".into(),
396            name: Some("Major Release".into()),
397            body: Some("## Breaking Changes\n- ...".into()),
398            draft: true,
399            prerelease: true,
400            target_commitish: Some("main".into()),
401        };
402        assert_eq!(args.tag_name, "v2.0.0");
403        assert_eq!(args.name.as_deref(), Some("Major Release"));
404        assert_eq!(args.body.as_deref(), Some("## Breaking Changes\n- ..."));
405        assert!(args.draft);
406        assert!(args.prerelease);
407        assert_eq!(args.target_commitish.as_deref(), Some("main"));
408    }
409
410    #[test]
411    fn test_create_release_args_should_be_cloneable() {
412        let args = CreateReleaseArgs {
413            tag_name: "v1.0.0".into(),
414            name: Some("v1".into()),
415            body: Some("body".into()),
416            draft: true,
417            prerelease: false,
418            target_commitish: Some("abc123".into()),
419        };
420        let cloned = args.clone();
421        assert_eq!(cloned.tag_name, args.tag_name);
422        assert_eq!(cloned.name, args.name);
423        assert_eq!(cloned.body, args.body);
424        assert_eq!(cloned.draft, args.draft);
425        assert_eq!(cloned.prerelease, args.prerelease);
426        assert_eq!(cloned.target_commitish, args.target_commitish);
427    }
428}