Skip to main content

gitflow_gitcode/
release.rs

1//! GitCode Release 提供者实现。
2//!
3//! 通过 `gitcode` CLI 实现 [`ReleaseProvider`] trait,支持 Release 的创建、列表、
4//! 查看、编辑、资源上传/下载及删除。
5//! 所有方法通过 `tokio::process::Command` 调用 `gc`,捕获 stdout 并解析 JSON。
6//!
7//! 例外:`list` 走 `gitcode api`,其响应字段名是 snake_case(`tag_name` / `html_url`),
8//! 与 [`ReleaseData`] 的 camelCase 线上命名不兼容,因此先反序列化为中间类型
9//! [`ReleaseApiResponse`] 再转换为 core 类型——与本 crate 的 `IssueApiResponse`
10//! 及 `gitflow-gitlab` 的同名类型同构。
11
12use async_trait::async_trait;
13use chrono::{DateTime, Utc};
14use gitflow_core::{
15    CoreError, DEFAULT_LIST_LIMIT, FetchStrategy, Paged, Result, Session, fetch_capped,
16    release::{CreateReleaseArgs, ReleaseData, ReleaseProvider},
17    types::{UserSummary, deserialize_u64_or_string_to_string},
18};
19use serde::Deserialize;
20use tracing::debug;
21
22use crate::{
23    error::parse_gitcode_error,
24    runner::{CommandRunner, RealCommandRunner},
25};
26
27/// `gc release` 请求的 JSON 字段列表。
28const RELEASE_FIELDS: &str =
29    "id,tagName,name,body,isDraft,isPrerelease,author,createdAt,publishedAt,url";
30
31// ── 中间 API 响应类型 ──────────────────────────────────────────────
32
33/// 反序列化「u64 / 字符串 / `null`」三种形态为 `Option<String>`。
34///
35/// 本地小助手,专用于本文件;不放进 `crates/core` 是因为它只多做一件
36/// `gitflow_core::types::deserialize_u64_or_string_to_string` 没做的事——
37/// 容忍 `null`(该函数没有 `visit_unit`,遇到 `null` 会硬报
38/// `invalid type: null`)。Gitee 血统的 API 常用 `null` 表示「这个 id 此刻
39/// 不存在」(例如作者账号已注销),而不是省略字段。
40fn deserialize_u64_or_string_or_null_to_string<'de, D>(
41    deserializer: D,
42) -> std::result::Result<Option<String>, D::Error>
43where
44    D: serde::Deserializer<'de>,
45{
46    use serde::de;
47
48    struct U64OrStringOrNullToString;
49    impl de::Visitor<'_> for U64OrStringOrNullToString {
50        type Value = Option<String>;
51
52        fn expecting(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
53            f.write_str("a u64 integer, a string, or null")
54        }
55
56        fn visit_u64<E: de::Error>(self, v: u64) -> std::result::Result<Option<String>, E> {
57            Ok(Some(v.to_string()))
58        }
59
60        fn visit_str<E: de::Error>(self, v: &str) -> std::result::Result<Option<String>, E> {
61            Ok(Some(v.to_string()))
62        }
63
64        fn visit_unit<E: de::Error>(self) -> std::result::Result<Option<String>, E> {
65            Ok(None)
66        }
67
68        fn visit_none<E: de::Error>(self) -> std::result::Result<Option<String>, E> {
69            Ok(None)
70        }
71    }
72
73    deserializer.deserialize_any(U64OrStringOrNullToString)
74}
75
76/// `gitcode api` release 响应中的作者对象。
77///
78/// 独立于 [`UserSummary`] 的原因:gitcode api 的 `id` 可能是数字也可能是字符串,
79/// 而 `UserSummary::id` 是 `String` 且未挂 `deserialize_u64_or_string_to_string`,
80/// 直接反序列化数字 id 会硬报 `invalid type: integer`。`login` 为 `Option<String>`:
81/// 账号已注销等场景下 gitcode 会把 `login` 置为 `null`(F1 第二轮修复)。
82#[derive(Debug, Clone, Deserialize)]
83struct ReleaseUserApi {
84    #[serde(default)]
85    login: Option<String>,
86    #[serde(default, deserialize_with = "deserialize_u64_or_string_to_string")]
87    id: String,
88}
89
90impl From<ReleaseUserApi> for UserSummary {
91    fn from(u: ReleaseUserApi) -> Self {
92        Self {
93            login: u.login.unwrap_or_default(),
94            id: u.id,
95        }
96    }
97}
98
99/// `gitcode api /repos/{owner}/{repo}/releases` 的响应结构。
100///
101/// 线上字段名为 snake_case,与 [`ReleaseData`] 的 camelCase
102/// (`tagName` / `createdAt` / `publishedAt`)不同,故必须经由本类型转换。
103///
104/// # 容错边界(务必精确,不要泛化这句话——本节已两次因过度概括而失实)
105///
106/// `#[serde(default)]` 只在字段**缺失**时生效;字段存在但类型不对,serde
107/// 依然会报错并使整条记录、进而整个 `releases` 数组反序列化失败。
108///
109/// ## 实际容忍 `null` 的字段
110///
111/// [`ReleaseApiResponse`] 的每个字段类型都是 `Option<T>`(`id` 的字段类型是
112/// `Option<String>`,见下),[`ReleaseUserApi::login`] 也是 `Option<String>`——
113/// 因此这些字段本身缺失、或值显式为 `null`,都会退化为默认值,不会让 `list`
114/// 失败:`id`(退化为 `0`)、`tag_name`(退化为空字符串)、`name`、`body`、
115/// `draft`(退化为 `false`)、`prerelease`(退化为 `false`)、`author`
116/// (退化为 `None`)、`author.login`(退化为空字符串,F1 第二轮修复——
117/// Gitee 血统 API 常用「账号已注销」→ `login: null` 这一形状)、
118/// `created_at`、`published_at`、`html_url`、`url`。
119///
120/// `id` 额外用本文件的 [`deserialize_u64_or_string_or_null_to_string`](而非
121/// `gitflow_core::types::deserialize_u64_or_string_to_string`,后者没有
122/// `visit_unit`、遇 `null` 仍会报错)容忍数字、字符串、`null` 三种形态,
123/// 与 [`ReleaseUserApi::id`] 的字符串/数字容忍同源,都是因为 gitcode 的 id
124/// 观测到过两种线上编码。
125///
126/// ## 仍然不容忍、会使整个 `list` 失败的情况
127///
128/// - **字段存在但类型错误**(例如 `"tag_name": 5`、`"author": "dev"`): `Option<T>`
129///   的默认/自定义反序列化只特殊处理 `null`,其余类型不匹配 仍会报 `invalid type`。
130/// - **`author.id` 为 `null`**:`ReleaseUserApi::id` 用的是
131///   `gitflow_core::types::deserialize_u64_or_string_to_string`(核心库,
132///   本次修复未改动),该函数没有 `visit_unit`,`null` 会报 `invalid type: null, expected a u64
133///   integer or string`。本次只扩展了 `release.id`(顶层)与 `author.login` 的 `null`
134///   容忍,`author.id` 未 纳入范围。
135/// - **`created_at` / `published_at` 存在且不是合法 RFC3339**(例如 `"2026-01-01
136///   00:00:00"`):`null` 或字段缺失没问题,但格式错误的字符串 仍会被 chrono
137///   拒绝并让整条记录失败——这不属于本次修复范围。
138#[derive(Debug, Clone, Deserialize)]
139struct ReleaseApiResponse {
140    #[serde(
141        default,
142        deserialize_with = "deserialize_u64_or_string_or_null_to_string"
143    )]
144    id: Option<String>,
145    #[serde(default)]
146    tag_name: Option<String>,
147    #[serde(default)]
148    name: Option<String>,
149    #[serde(default)]
150    body: Option<String>,
151    #[serde(default)]
152    draft: Option<bool>,
153    #[serde(default)]
154    prerelease: Option<bool>,
155    #[serde(default)]
156    author: Option<ReleaseUserApi>,
157    #[serde(default)]
158    created_at: Option<DateTime<Utc>>,
159    #[serde(default)]
160    published_at: Option<DateTime<Utc>>,
161    /// 可浏览的网页地址。gitcode 沿用 GitHub 的切分:`url` 是 API self-link,
162    /// `html_url` 才是网页地址。`release view`(CLI 路径)返回的是网页地址,
163    /// 故此处优先取 `html_url`,避免同一字段在 `list` 与 `view` 下含义不同。
164    #[serde(default)]
165    html_url: Option<String>,
166    #[serde(default)]
167    url: Option<String>,
168}
169
170impl From<ReleaseApiResponse> for ReleaseData {
171    fn from(api: ReleaseApiResponse) -> Self {
172        Self {
173            id: api.id.and_then(|s| s.parse().ok()).unwrap_or(0),
174            tag_name: api.tag_name.unwrap_or_default(),
175            name: api.name,
176            body: api.body,
177            draft: api.draft.unwrap_or_default(),
178            prerelease: api.prerelease.unwrap_or_default(),
179            author: api.author.map(UserSummary::from),
180            created_at: api.created_at,
181            published_at: api.published_at,
182            url: api.html_url.or(api.url).unwrap_or_default(),
183        }
184    }
185}
186
187/// GitCode Release 提供者,通过 `gitcode` CLI 操作。
188///
189/// 该结构体通过调用 `gitcode` CLI 实现 [`ReleaseProvider`] trait 的所有方法,
190/// 使上层命令能够以统一的方式操作 GitCode Release。
191///
192/// 命令执行通过 [`CommandRunner`] 抽象,生产环境默认使用
193/// [`RealCommandRunner`],测试可注入自定义 runner 以模拟成功或失败场景。
194///
195/// # Examples
196///
197/// ```no_run
198/// use gitflow_gitcode::GitCodeReleaseProvider;
199///
200/// let provider = GitCodeReleaseProvider::new("octocat/hello-world");
201/// ```
202#[derive(Debug, Clone)]
203pub struct GitCodeReleaseProvider<R: CommandRunner = RealCommandRunner> {
204    /// GitCode `owner/repo`,如 `"byx-darwin/gitflow-cli"`。
205    repo: String,
206    /// 用于执行 `gitcode` CLI 命令的 runner。
207    runner: R,
208}
209
210impl GitCodeReleaseProvider<RealCommandRunner> {
211    /// 创建新的 GitCode Release 提供者。
212    ///
213    /// `repo` 格式为 `owner/repo`。
214    #[must_use]
215    pub fn new(repo: impl Into<String>) -> Self {
216        Self {
217            repo: repo.into(),
218            runner: RealCommandRunner,
219        }
220    }
221
222    /// Create a new provider from a shared [`Session`].
223    ///
224    /// This enables state reuse across multiple operations in workflow chains.
225    #[must_use]
226    pub fn with_session(session: &Session) -> Self {
227        Self {
228            repo: session.repo.clone(),
229            runner: RealCommandRunner,
230        }
231    }
232}
233
234impl<R: CommandRunner> GitCodeReleaseProvider<R> {
235    /// 使用自定义 [`CommandRunner`] 创建提供者。
236    ///
237    /// 主要用于测试,可注入模拟 runner 以控制 `gitcode` CLI 的输出。
238    /// `repo` 格式为 `owner/repo`。
239    #[must_use]
240    pub fn with_runner(repo: impl Into<String>, runner: R) -> Self {
241        Self {
242            repo: repo.into(),
243            runner,
244        }
245    }
246}
247
248#[async_trait]
249impl<R: CommandRunner + 'static> ReleaseProvider for GitCodeReleaseProvider<R> {
250    async fn create(&self, args: CreateReleaseArgs) -> Result<ReleaseData> {
251        let binary = crate::gitcode_binary();
252        let mut cmd_args: Vec<&str> = vec![
253            "release",
254            "create",
255            &args.tag_name,
256            "-R",
257            &self.repo,
258            "--json",
259            RELEASE_FIELDS,
260        ];
261
262        if let Some(ref name) = args.name {
263            cmd_args.push("--title");
264            cmd_args.push(name);
265        }
266
267        if let Some(ref body) = args.body {
268            cmd_args.push("--notes");
269            cmd_args.push(body);
270        }
271
272        if args.draft {
273            cmd_args.push("--draft");
274        }
275
276        if args.prerelease {
277            cmd_args.push("--prerelease");
278        }
279
280        if let Some(ref commitish) = args.target_commitish {
281            cmd_args.push("--target");
282            cmd_args.push(commitish);
283        }
284
285        debug!(
286            repo = %self.repo,
287            tag = %args.tag_name,
288            "spawning `gc release create`"
289        );
290
291        let output = self
292            .runner
293            .run(&binary, &cmd_args)
294            .await
295            .map_err(|e| CoreError::Platform(format!("Failed to spawn gitcode: {e}")))?;
296
297        if !output.status.success() {
298            return Err(parse_gitcode_error(&output.stderr).into());
299        }
300
301        // If JSON parsing fails, the release was still created successfully
302        // Try to fetch it via view
303        match serde_json::from_slice::<ReleaseData>(&output.stdout) {
304            Ok(release) => Ok(release),
305            Err(_) => self.view(&args.tag_name).await,
306        }
307    }
308
309    /// 列出 Release,按页抓取至多 `limit` 条。
310    ///
311    /// 走 `gitcode api` 而非 `release list` 子命令:实测(gitcode-cli 0.12.0)
312    /// `release list` **没有任何分页旗标**(只有 `-L/--limit`),而其 API 层的
313    /// `per_page` 被静默封顶在 100,因此 CLI 路径无法诚实报告截断。api 路径与
314    /// 本 crate 的 `issue comments`(`issue.rs`)同构。
315    ///
316    /// api 响应是 snake_case,经 [`ReleaseApiResponse`] 转换为 [`ReleaseData`]。
317    ///
318    /// `create` / `view` 等其余方法仍走 CLI 子命令,不受影响。
319    ///
320    /// # Errors
321    ///
322    /// 当 `gitcode` CLI 调用失败或响应无法反序列化时返回错误。
323    async fn list(&self, limit: Option<u32>) -> Result<Paged<ReleaseData>> {
324        let binary = crate::gitcode_binary();
325        let binary = &binary;
326        let cap = limit.unwrap_or(DEFAULT_LIST_LIMIT);
327        let repo = &self.repo;
328        let runner = &self.runner;
329        let per_page = cap.saturating_add(1).min(crate::GITCODE_API_MAX_PER_PAGE);
330
331        debug!(repo = %self.repo, cap, per_page, "spawning `gitcode api` GET releases");
332
333        fetch_capped(
334            FetchStrategy::Paged { per_page },
335            cap,
336            |page, per_page| async move {
337                let api_path = format!("/repos/{repo}/releases?per_page={per_page}&page={page}");
338
339                let output = runner.run(binary, &["api", &api_path]).await.map_err(|e| {
340                    CoreError::Platform(format!("Failed to spawn gitcode api: {e}"))
341                })?;
342
343                if !output.status.success() {
344                    return Err(parse_gitcode_error(&output.stderr).into());
345                }
346
347                let releases: Vec<ReleaseApiResponse> =
348                    serde_json::from_slice(&output.stdout).map_err(CoreError::Serialization)?;
349                Ok(releases.into_iter().map(ReleaseData::from).collect())
350            },
351        )
352        .await
353    }
354
355    async fn view(&self, tag_name: &str) -> Result<ReleaseData> {
356        let binary = crate::gitcode_binary();
357        debug!(repo = %self.repo, tag = %tag_name, "spawning `gc release view`");
358
359        let output = self
360            .runner
361            .run(
362                &binary,
363                &["release", "view", tag_name, "-R", &self.repo, "--json"],
364            )
365            .await
366            .map_err(|e| CoreError::Platform(format!("Failed to spawn gitcode: {e}")))?;
367
368        if !output.status.success() {
369            return Err(parse_gitcode_error(&output.stderr).into());
370        }
371
372        let release: ReleaseData =
373            serde_json::from_slice(&output.stdout).map_err(CoreError::Serialization)?;
374
375        Ok(release)
376    }
377
378    async fn edit(&self, tag_name: &str, args: CreateReleaseArgs) -> Result<ReleaseData> {
379        let binary = crate::gitcode_binary();
380        let mut cmd_args: Vec<&str> = vec![
381            "release",
382            "edit",
383            tag_name,
384            "-R",
385            &self.repo,
386            "--json",
387            RELEASE_FIELDS,
388        ];
389
390        if let Some(ref name) = args.name {
391            cmd_args.push("--title");
392            cmd_args.push(name);
393        }
394
395        if let Some(ref body) = args.body {
396            cmd_args.push("--notes");
397            cmd_args.push(body);
398        }
399
400        if args.draft {
401            cmd_args.push("--draft");
402        }
403
404        if args.prerelease {
405            cmd_args.push("--prerelease");
406        }
407
408        debug!(
409            repo = %self.repo,
410            tag = %tag_name,
411            "spawning `gc release edit`"
412        );
413
414        let output = self
415            .runner
416            .run(&binary, &cmd_args)
417            .await
418            .map_err(|e| CoreError::Platform(format!("Failed to spawn gitcode: {e}")))?;
419
420        if !output.status.success() {
421            return Err(parse_gitcode_error(&output.stderr).into());
422        }
423
424        // If JSON parsing fails, try to fetch the edited release
425        match serde_json::from_slice::<ReleaseData>(&output.stdout) {
426            Ok(release) => Ok(release),
427            Err(_) => self.view(tag_name).await,
428        }
429    }
430
431    async fn delete(&self, tag_name: &str) -> Result<()> {
432        let binary = crate::gitcode_binary();
433        debug!(repo = %self.repo, tag = %tag_name, "spawning `gc release delete`");
434
435        let output = self
436            .runner
437            .run(&binary, &["release", "delete", tag_name, "-R", &self.repo])
438            .await
439            .map_err(|e| CoreError::Platform(format!("Failed to spawn gitcode: {e}")))?;
440
441        if !output.status.success() {
442            return Err(parse_gitcode_error(&output.stderr).into());
443        }
444
445        Ok(())
446    }
447
448    async fn upload_asset(&self, tag_name: &str, file_path: &str, _asset_name: &str) -> Result<()> {
449        let binary = crate::gitcode_binary();
450        debug!(
451            repo = %self.repo,
452            tag = %tag_name,
453            file = %file_path,
454            "spawning `gc release upload`"
455        );
456
457        let output = self
458            .runner
459            .run(
460                &binary,
461                &["release", "upload", tag_name, file_path, "-R", &self.repo],
462            )
463            .await
464            .map_err(|e| CoreError::Platform(format!("Failed to spawn gitcode: {e}")))?;
465
466        if !output.status.success() {
467            return Err(parse_gitcode_error(&output.stderr).into());
468        }
469
470        Ok(())
471    }
472
473    async fn download_asset(
474        &self,
475        tag_name: &str,
476        asset_name: &str,
477        output_path: &str,
478    ) -> Result<()> {
479        let binary = crate::gitcode_binary();
480        debug!(
481            repo = %self.repo,
482            tag = %tag_name,
483            asset = %asset_name,
484            output = %output_path,
485            "spawning `gc release download`"
486        );
487
488        let output = self
489            .runner
490            .run(
491                &binary,
492                &[
493                    "release",
494                    "download",
495                    tag_name,
496                    "-R",
497                    &self.repo,
498                    "--asset",
499                    asset_name,
500                    "--output",
501                    output_path,
502                ],
503            )
504            .await
505            .map_err(|e| CoreError::Platform(format!("Failed to spawn gitcode: {e}")))?;
506
507        if !output.status.success() {
508            return Err(parse_gitcode_error(&output.stderr).into());
509        }
510
511        Ok(())
512    }
513}
514
515#[cfg(test)]
516mod tests {
517    use super::*;
518    use crate::runner::{MockCommandRunner, SequencedMockCommandRunner};
519
520    #[test]
521    fn test_should_construct_gitcode_release_provider() {
522        let provider = GitCodeReleaseProvider::new("octocat/hello-world");
523        assert_eq!(provider.repo, "octocat/hello-world");
524    }
525
526    #[test]
527    fn test_should_construct_gitcode_release_provider_from_string() {
528        let repo = String::from("octocat/hello-world");
529        let provider = GitCodeReleaseProvider::new(repo);
530        assert_eq!(provider.repo, "octocat/hello-world");
531    }
532
533    #[test]
534    fn test_should_debug_format_provider() {
535        let provider = GitCodeReleaseProvider::new("octocat/hello-world");
536        let debug = format!("{provider:?}");
537        assert!(debug.contains("GitCodeReleaseProvider"));
538        assert!(debug.contains("octocat/hello-world"));
539    }
540
541    #[test]
542    fn test_should_clone_gitcode_release_provider() {
543        let original = GitCodeReleaseProvider::new("owner/repo");
544        let cloned = original.clone();
545        assert_eq!(original.repo, cloned.repo);
546    }
547
548    // --- Failure-path tests using an injected MockCommandRunner ---
549
550    fn sample_release_args() -> CreateReleaseArgs {
551        CreateReleaseArgs {
552            tag_name: "v1.0.0".to_string(),
553            name: Some("Release 1.0.0".to_string()),
554            body: Some("First stable release".to_string()),
555            draft: false,
556            prerelease: false,
557            target_commitish: None,
558        }
559    }
560
561    #[tokio::test]
562    async fn test_should_return_platform_error_when_gc_fails_for_create() {
563        let runner = MockCommandRunner::failure("tag already exists", 256);
564        let provider = GitCodeReleaseProvider::with_runner("owner/repo", runner);
565
566        let result = provider.create(sample_release_args()).await;
567
568        assert!(matches!(
569            result.unwrap_err(),
570            gitflow_core::CoreError::Cli(_)
571        ));
572    }
573
574    #[tokio::test]
575    async fn test_should_return_serialization_error_on_invalid_json_for_create() {
576        // create parses ReleaseData; on failure it falls back to view, which
577        // receives the same non-JSON stdout and fails to deserialize.
578        let runner = MockCommandRunner::success("not valid json");
579        let provider = GitCodeReleaseProvider::with_runner("owner/repo", runner);
580
581        let result = provider.create(sample_release_args()).await;
582
583        assert!(matches!(
584            result.unwrap_err(),
585            gitflow_core::CoreError::Serialization(_)
586        ));
587    }
588
589    #[tokio::test]
590    async fn test_should_return_platform_error_when_gc_fails_for_list() {
591        let runner = MockCommandRunner::failure("forbidden", 256);
592        let provider = GitCodeReleaseProvider::with_runner("owner/repo", runner);
593
594        let result = provider.list(None).await;
595
596        assert!(matches!(
597            result.unwrap_err(),
598            gitflow_core::CoreError::Cli(_)
599        ));
600    }
601
602    #[tokio::test]
603    async fn test_should_return_serialization_error_on_invalid_json_for_list() {
604        let runner = MockCommandRunner::success("invalid");
605        let provider = GitCodeReleaseProvider::with_runner("owner/repo", runner);
606
607        let result = provider.list(None).await;
608
609        assert!(matches!(
610            result.unwrap_err(),
611            gitflow_core::CoreError::Serialization(_)
612        ));
613    }
614
615    #[tokio::test]
616    async fn test_should_return_platform_error_when_gc_fails_for_view() {
617        let runner = MockCommandRunner::failure("release not found", 256);
618        let provider = GitCodeReleaseProvider::with_runner("owner/repo", runner);
619
620        let result = provider.view("v1.0.0").await;
621
622        assert!(matches!(
623            result.unwrap_err(),
624            gitflow_core::CoreError::Cli(_)
625        ));
626    }
627
628    #[tokio::test]
629    async fn test_should_return_serialization_error_on_invalid_json_for_view() {
630        let runner = MockCommandRunner::success("not valid json");
631        let provider = GitCodeReleaseProvider::with_runner("owner/repo", runner);
632
633        let result = provider.view("v1.0.0").await;
634
635        assert!(matches!(
636            result.unwrap_err(),
637            gitflow_core::CoreError::Serialization(_)
638        ));
639    }
640
641    #[tokio::test]
642    async fn test_should_return_platform_error_when_gc_fails_for_edit() {
643        let runner = MockCommandRunner::failure("release not found", 256);
644        let provider = GitCodeReleaseProvider::with_runner("owner/repo", runner);
645
646        let result = provider.edit("v1.0.0", sample_release_args()).await;
647
648        assert!(matches!(
649            result.unwrap_err(),
650            gitflow_core::CoreError::Cli(_)
651        ));
652    }
653
654    #[tokio::test]
655    async fn test_should_return_serialization_error_on_invalid_json_for_edit() {
656        // edit parses ReleaseData; on failure it falls back to view, which
657        // receives the same non-JSON stdout and fails to deserialize.
658        let runner = MockCommandRunner::success("not valid json");
659        let provider = GitCodeReleaseProvider::with_runner("owner/repo", runner);
660
661        let result = provider.edit("v1.0.0", sample_release_args()).await;
662
663        assert!(matches!(
664            result.unwrap_err(),
665            gitflow_core::CoreError::Serialization(_)
666        ));
667    }
668
669    #[tokio::test]
670    async fn test_should_return_platform_error_when_gc_fails_for_delete() {
671        let runner = MockCommandRunner::failure("release not found", 256);
672        let provider = GitCodeReleaseProvider::with_runner("owner/repo", runner);
673
674        let result = provider.delete("v1.0.0").await;
675
676        assert!(matches!(
677            result.unwrap_err(),
678            gitflow_core::CoreError::Cli(_)
679        ));
680    }
681
682    #[tokio::test]
683    async fn test_should_return_platform_error_when_gc_fails_for_upload_asset() {
684        let runner = MockCommandRunner::failure("upload failed", 256);
685        let provider = GitCodeReleaseProvider::with_runner("owner/repo", runner);
686
687        let result = provider
688            .upload_asset("v1.0.0", "/tmp/artifact.tar.gz", "artifact.tar.gz")
689            .await;
690
691        assert!(matches!(
692            result.unwrap_err(),
693            gitflow_core::CoreError::Cli(_)
694        ));
695    }
696
697    #[tokio::test]
698    async fn test_should_return_platform_error_when_gc_fails_for_download_asset() {
699        let runner = MockCommandRunner::failure("asset not found", 256);
700        let provider = GitCodeReleaseProvider::with_runner("owner/repo", runner);
701
702        let result = provider
703            .download_asset("v1.0.0", "artifact.tar.gz", "/tmp/out.tar.gz")
704            .await;
705
706        assert!(matches!(
707            result.unwrap_err(),
708            gitflow_core::CoreError::Cli(_)
709        ));
710    }
711
712    // --- Deserialization tests ---
713
714    #[test]
715    fn test_should_deserialize_release_data_from_gitcode_output() {
716        let json = br#"{
717            "id": 100,
718            "tagName": "v2.0.0",
719            "name": "GitCode Release",
720            "body": "Changelog here",
721            "draft": false,
722            "prerelease": false,
723            "author": {"login": "dev", "id": "42"},
724            "createdAt": "2026-02-01T00:00:00Z",
725            "publishedAt": "2026-02-01T12:00:00Z",
726            "url": "https://gitcode.com/owner/repo/releases/tag/v2.0.0"
727        }"#;
728
729        let release: ReleaseData = serde_json::from_slice(json).expect("valid ReleaseData JSON");
730        assert_eq!(release.id, 100);
731        assert_eq!(release.tag_name, "v2.0.0");
732        assert_eq!(release.name.as_deref(), Some("GitCode Release"));
733        assert_eq!(release.body.as_deref(), Some("Changelog here"));
734        assert!(!release.draft);
735        assert!(!release.prerelease);
736        assert_eq!(release.author.as_ref().expect("author").login, "dev");
737        assert_eq!(release.author.as_ref().expect("author").id, "42");
738    }
739
740    #[test]
741    fn test_should_deserialize_empty_release_list_from_gitcode_output() {
742        let json = b"[]";
743        let releases: Vec<ReleaseData> = serde_json::from_slice(json).expect("valid empty list");
744        assert!(releases.is_empty());
745    }
746
747    #[test]
748    fn test_should_deserialize_draft_release_from_gitcode_output() {
749        let json = br#"{
750            "id": 7,
751            "tagName": "v0.1.0-rc1",
752            "name": null,
753            "body": null,
754            "draft": true,
755            "prerelease": true,
756            "author": {"login": "bot", "id": "0"},
757            "createdAt": "2026-03-01T00:00:00Z",
758            "publishedAt": null,
759            "url": "https://gitcode.com/owner/repo/releases/tag/v0.1.0-rc1"
760        }"#;
761
762        let release: ReleaseData = serde_json::from_slice(json).expect("valid draft ReleaseData");
763        assert!(release.draft);
764        assert!(release.prerelease);
765        assert!(release.name.is_none());
766        assert!(release.body.is_none());
767        assert!(release.published_at.is_none());
768    }
769
770    // --- with_runner constructor ---
771
772    #[test]
773    fn test_should_create_provider_with_custom_runner() {
774        let runner = MockCommandRunner::success("");
775        let provider = GitCodeReleaseProvider::with_runner("owner/repo", runner);
776        assert_eq!(provider.repo, "owner/repo");
777    }
778
779    // --- Success-path tests ---
780
781    fn valid_release_json() -> &'static str {
782        r#"{
783            "id": 1,
784            "tagName": "v1.0.0",
785            "name": "Release 1.0.0",
786            "body": "First stable release",
787            "draft": false,
788            "prerelease": false,
789            "author": {"login": "dev", "id": "1"},
790            "createdAt": "2026-01-01T00:00:00Z",
791            "publishedAt": "2026-01-01T00:00:00Z",
792            "url": "https://gitcode.com/owner/repo/releases/tag/v1.0.0"
793        }"#
794    }
795
796    /// `gitcode api /repos/{owner}/{repo}/releases` 的真实响应形状:snake_case
797    /// 字段名、数字型 author id、`url` 与 `html_url` 并存。
798    ///
799    /// 这是 C1 的回归护栏——用 [`ReleaseData`] 直接反序列化这份 payload 会得到
800    /// `missing field \`tagName\``。
801    fn valid_release_api_json() -> &'static str {
802        r#"{
803            "id": 1,
804            "tag_name": "v1.0.0",
805            "name": "Release 1.0.0",
806            "body": "First stable release",
807            "draft": false,
808            "prerelease": false,
809            "author": {"login": "dev", "id": 1},
810            "created_at": "2026-01-01T00:00:00Z",
811            "published_at": "2026-01-01T00:00:00Z",
812            "html_url": "https://gitcode.com/owner/repo/releases/tag/v1.0.0",
813            "url": "https://api.gitcode.com/repos/owner/repo/releases/1"
814        }"#
815    }
816
817    #[tokio::test]
818    async fn test_should_view_release_successfully() {
819        let runner = MockCommandRunner::success(valid_release_json());
820        let provider = GitCodeReleaseProvider::with_runner("owner/repo", runner);
821
822        let release = provider.view("v1.0.0").await.expect("view should succeed");
823        assert_eq!(release.tag_name, "v1.0.0");
824        assert_eq!(release.name.as_deref(), Some("Release 1.0.0"));
825        assert_eq!(release.id, 1);
826    }
827
828    #[tokio::test]
829    async fn test_should_list_releases_successfully() {
830        let json = format!("[{}]", valid_release_api_json());
831        let runner = MockCommandRunner::success(&json);
832        let provider = GitCodeReleaseProvider::with_runner("owner/repo", runner);
833
834        let paged = provider.list(None).await.expect("list should succeed");
835        assert_eq!(paged.items.len(), 1);
836        assert_eq!(paged.items[0].tag_name, "v1.0.0");
837    }
838
839    #[tokio::test]
840    async fn test_should_fetch_gitcode_releases_via_api_with_pagination() {
841        // cap=100 → per_page=100,want=101;首页满 100 条 ⇒ 必然发出第二页。
842        // cap 必须 ≥ 100,否则 per_page 恰为 cap+1,循环只发一次调用,
843        // 断言 calls[1] 会直接索引越界。
844        let one = valid_release_api_json();
845        let page = format!("[{}]", vec![one; 100].join(","));
846        let runner = SequencedMockCommandRunner::from_results(&[(true, &page), (true, &page)]);
847        let provider = GitCodeReleaseProvider::with_runner("owner/repo", runner.clone());
848
849        let paged = provider.list(Some(100)).await.expect("list should succeed");
850
851        assert_eq!(paged.items.len(), 100);
852        assert!(paged.truncated);
853
854        let calls = runner.recorded_calls();
855        assert_eq!(
856            calls.len(),
857            2,
858            "必须真的翻到第二页,实际调用数: {}",
859            calls.len()
860        );
861        // 整串相等,而非 `contains`:`"per_page=1001".contains("per_page=100")`
862        // 与 `"per_page=100".contains("page=1")` 都为真,子串断言检测不出钳位失效。
863        assert_eq!(
864            calls[0].1,
865            vec!["api", "/repos/owner/repo/releases?per_page=100&page=1"]
866        );
867        assert_eq!(
868            calls[1].1,
869            vec!["api", "/repos/owner/repo/releases?per_page=100&page=2"]
870        );
871    }
872
873    #[tokio::test]
874    async fn test_should_deserialize_release_from_gitcode_api_response() {
875        // 钉住 api 响应(snake_case)→ ReleaseData 的字段映射(本机无带 release 的
876        // 公开 gitcode 仓库可验,故以 fixture 覆盖)。
877        let runner = MockCommandRunner::success(&format!("[{}]", valid_release_api_json()));
878        let provider = GitCodeReleaseProvider::with_runner("owner/repo", runner);
879
880        let paged = provider.list(None).await.expect("list should succeed");
881
882        assert_eq!(paged.items.len(), 1);
883        let release = &paged.items[0];
884        assert_eq!(release.id, 1);
885        assert_eq!(release.tag_name, "v1.0.0");
886        assert_eq!(release.name.as_deref(), Some("Release 1.0.0"));
887        assert_eq!(release.body.as_deref(), Some("First stable release"));
888        assert!(!release.draft);
889        assert!(!release.prerelease);
890        // 数字型 author id 必须被接受并转成字符串。
891        let author = release.author.as_ref().expect("author");
892        assert_eq!(author.login, "dev");
893        assert_eq!(author.id, "1");
894        assert_eq!(
895            release.created_at.map(|dt| dt.to_rfc3339()),
896            Some("2026-01-01T00:00:00+00:00".to_string())
897        );
898        assert!(release.published_at.is_some());
899        // html_url 优先于 API self-link。
900        assert_eq!(
901            release.url,
902            "https://gitcode.com/owner/repo/releases/tag/v1.0.0"
903        );
904    }
905
906    #[test]
907    fn test_should_reject_snake_case_api_payload_when_using_core_release_data() {
908        // C1 的成因说明:ReleaseData 是 camelCase 线上命名,直接吃 api 响应会失败。
909        // 这两条断言把「必须有中间类型」这一事实钉住,防止日后有人把它去掉。
910
911        // 成因一:字段名不匹配。剥掉 author 以隔离出 tagName 这一项。
912        let no_author = r#"{
913            "tag_name": "v1.0.0",
914            "draft": false,
915            "prerelease": false,
916            "created_at": "2026-01-01T00:00:00Z"
917        }"#;
918        let err = serde_json::from_str::<ReleaseData>(no_author)
919            .expect_err("ReleaseData must not accept a snake_case api payload");
920        assert!(err.to_string().contains("tagName"), "实际错误: {err}");
921
922        // 成因二:UserSummary::id 是 String,api 的数字 id 会硬报类型错误。
923        let err = serde_json::from_str::<ReleaseData>(valid_release_api_json())
924            .expect_err("ReleaseData must not accept the full api payload either");
925        assert!(
926            err.to_string().contains("invalid type: integer"),
927            "实际错误: {err}"
928        );
929    }
930
931    #[tokio::test]
932    async fn test_should_prefer_html_url_over_api_self_link_for_release_url() {
933        let json = r#"[{
934            "tag_name": "v2.0.0",
935            "url": "https://api.gitcode.com/repos/owner/repo/releases/9",
936            "html_url": "https://gitcode.com/owner/repo/releases/tag/v2.0.0"
937        }]"#;
938        let runner = MockCommandRunner::success(json);
939        let provider = GitCodeReleaseProvider::with_runner("owner/repo", runner);
940
941        let paged = provider.list(None).await.expect("list should succeed");
942
943        assert_eq!(
944            paged.items[0].url,
945            "https://gitcode.com/owner/repo/releases/tag/v2.0.0"
946        );
947    }
948
949    #[tokio::test]
950    async fn test_should_fall_back_to_url_when_api_omits_html_url() {
951        let json = r#"[{
952            "tag_name": "v2.0.0",
953            "url": "https://gitcode.com/owner/repo/releases/tag/v2.0.0"
954        }]"#;
955        let runner = MockCommandRunner::success(json);
956        let provider = GitCodeReleaseProvider::with_runner("owner/repo", runner);
957
958        let paged = provider.list(None).await.expect("list should succeed");
959
960        assert_eq!(
961            paged.items[0].url,
962            "https://gitcode.com/owner/repo/releases/tag/v2.0.0"
963        );
964    }
965
966    #[tokio::test]
967    async fn test_should_degrade_predictably_for_minimal_api_release_object() {
968        // 形状不匹配时必须整体退化而非半途失败:所有字段都有 default。
969        let runner = MockCommandRunner::success(r#"[{"tag_name": "v0.0.1"}]"#);
970        let provider = GitCodeReleaseProvider::with_runner("owner/repo", runner);
971
972        let paged = provider.list(None).await.expect("list should succeed");
973
974        let release = &paged.items[0];
975        assert_eq!(release.tag_name, "v0.0.1");
976        assert_eq!(release.id, 0);
977        assert!(!release.draft);
978        assert!(!release.prerelease);
979        assert!(release.author.is_none());
980        assert!(release.published_at.is_none());
981        assert!(release.url.is_empty());
982        assert!(
983            release.created_at.is_none(),
984            "missing created_at must stay None, not fall back to Utc::now()"
985        );
986    }
987
988    #[tokio::test]
989    async fn test_should_accept_string_author_id_from_api() {
990        let json = r#"[{
991            "tag_name": "v1.0.0",
992            "author": {"login": "dev", "id": "42"}
993        }]"#;
994        let runner = MockCommandRunner::success(json);
995        let provider = GitCodeReleaseProvider::with_runner("owner/repo", runner);
996
997        let paged = provider.list(None).await.expect("list should succeed");
998
999        assert_eq!(paged.items[0].author.as_ref().expect("author").id, "42");
1000    }
1001
1002    #[tokio::test]
1003    async fn test_should_deserialize_real_gitcode_release_api_response() {
1004        // 真实响应形状(2026-09-20 对 byx-darwin/NexaTrade 已登录 gitcode CLI 的
1005        // 实测,Issue #368 F1):`gitcode api /repos/{repo}/releases` 返回的对象
1006        // 里,`id`/`draft`/`html_url`/`url`/`published_at` 全部**完全缺失**
1007        // (不是 `null`),`author.id` 是字符串编码,`created_at` 带时区偏移而非
1008        // `Z`。额外字段 `assets`/`release_status`/`target_commitish` 未建模,
1009        // 应被 serde 静默忽略而不影响其余字段。此测试钉住这次实测结论:现有
1010        // `#[serde(default)]` 容错边界已足够,无需修改映射逻辑。
1011        let json = r#"[{
1012            "tag_name": "v0.1.0-test-issue368",
1013            "target_commitish": "223bb9d0d96331abc9d97074c0644097fd68d96f",
1014            "prerelease": false,
1015            "name": "Test release for Issue #368 verification",
1016            "body": "临时测试 release,用于实测 gitcode release list API 响应形状(Issue #368),验证完成后会删除。",
1017            "author": {
1018                "id": "812276",
1019                "login": "byx-darwin",
1020                "name": "baoyx",
1021                "avatar_url": "https://cdn-img.gitcode.com/example.png",
1022                "html_url": "https://gitcode.com/byx-darwin",
1023                "type": "User",
1024                "url": "https://api.gitcode.com/api/v5/users/byx-darwin"
1025            },
1026            "created_at": "2026-09-20T22:22:44+08:00",
1027            "assets": [
1028                {
1029                    "browser_download_url": "https://raw.gitcode.com/byx-darwin/NexaTrade/archive/refs/heads/v0.1.0-test-issue368.zip",
1030                    "name": "v0.1.0-test-issue368.zip",
1031                    "type": "source"
1032                }
1033            ],
1034            "release_status": "none"
1035        }]"#;
1036        let runner = MockCommandRunner::success(json);
1037        let provider = GitCodeReleaseProvider::with_runner("owner/repo", runner);
1038
1039        let paged = provider
1040            .list(None)
1041            .await
1042            .expect("real response shape should not fail list");
1043
1044        let release = &paged.items[0];
1045        assert_eq!(release.tag_name, "v0.1.0-test-issue368");
1046        assert_eq!(release.id, 0, "缺失的 id 应退化为 0");
1047        assert!(!release.draft, "缺失的 draft 应退化为 false");
1048        assert!(!release.prerelease);
1049        assert_eq!(
1050            release.name.as_deref(),
1051            Some("Test release for Issue #368 verification")
1052        );
1053        assert!(
1054            release.url.is_empty(),
1055            "缺失的 html_url/url 应退化为空字符串"
1056        );
1057        assert!(
1058            release.published_at.is_none(),
1059            "缺失的 published_at 应退化为 None"
1060        );
1061        let author = release.author.as_ref().expect("author present");
1062        assert_eq!(author.id, "812276");
1063        assert_eq!(author.login, "byx-darwin");
1064        assert_eq!(
1065            release.created_at,
1066            Some(
1067                chrono::DateTime::parse_from_rfc3339("2026-09-20T22:22:44+08:00")
1068                    .expect("valid rfc3339")
1069                    .with_timezone(&Utc)
1070            )
1071        );
1072    }
1073
1074    #[tokio::test]
1075    async fn test_should_accept_string_release_id_from_api() {
1076        // gitcode 的 release id 与 author id 同源,同样可能是字符串。F1: id
1077        // 之前是裸 u64,字符串形态会让整个 list 反序列化失败。
1078        let json = r#"[{
1079            "id": "12",
1080            "tag_name": "v1.0.0"
1081        }]"#;
1082        let runner = MockCommandRunner::success(json);
1083        let provider = GitCodeReleaseProvider::with_runner("owner/repo", runner);
1084
1085        let paged = provider.list(None).await.expect("list should succeed");
1086
1087        assert_eq!(paged.items[0].id, 12);
1088    }
1089
1090    #[tokio::test]
1091    async fn test_should_degrade_release_flags_when_null_in_api_response() {
1092        // Gitee 血统的 API 常用 null 表示「此概念在这里不存在」,而非省略字段。
1093        // F1: tag_name/draft/prerelease 之前是裸类型,null 会让整个 list 失败。
1094        let json = r#"[{
1095            "id": 1,
1096            "tag_name": null,
1097            "draft": null,
1098            "prerelease": null
1099        }]"#;
1100        let runner = MockCommandRunner::success(json);
1101        let provider = GitCodeReleaseProvider::with_runner("owner/repo", runner);
1102
1103        let paged = provider.list(None).await.expect("list should succeed");
1104
1105        let release = &paged.items[0];
1106        assert_eq!(release.tag_name, "");
1107        assert!(!release.draft);
1108        assert!(!release.prerelease);
1109    }
1110
1111    #[tokio::test]
1112    async fn test_should_degrade_release_id_to_zero_when_null_in_api_response() {
1113        // F1 第二轮:id 此前用 deserialize_u64_or_string_to_string,该函数没有
1114        // visit_unit,null 会硬报 `invalid type: null`。补上本地 null 容忍。
1115        let json = r#"[{
1116            "id": null,
1117            "tag_name": "v1.0.0"
1118        }]"#;
1119        let runner = MockCommandRunner::success(json);
1120        let provider = GitCodeReleaseProvider::with_runner("owner/repo", runner);
1121
1122        let paged = provider.list(None).await.expect("list should succeed");
1123
1124        assert_eq!(paged.items[0].id, 0);
1125    }
1126
1127    #[tokio::test]
1128    async fn test_should_degrade_author_login_to_empty_when_null_in_api_response() {
1129        // F1 第二轮:Gitee 血统 API 常用「作者已注销」→ login: null 这一形状,
1130        // ReleaseUserApi.login 此前是裸 String,null 会让整个 list 失败。
1131        let json = r#"[{
1132            "id": 1,
1133            "tag_name": "v1.0.0",
1134            "author": {"login": null, "id": 42}
1135        }]"#;
1136        let runner = MockCommandRunner::success(json);
1137        let provider = GitCodeReleaseProvider::with_runner("owner/repo", runner);
1138
1139        let paged = provider.list(None).await.expect("list should succeed");
1140
1141        let author = paged.items[0].author.as_ref().expect("author");
1142        assert_eq!(author.login, "");
1143        assert_eq!(author.id, "42");
1144    }
1145
1146    #[tokio::test]
1147    async fn test_should_fail_list_when_created_at_is_not_rfc3339() {
1148        // 钉住容错边界:null/缺失可以退化,但格式错误的字符串(非 RFC3339)
1149        // 仍然必须整体失败——这不是本次修复要处理的场景,文档不得声称已覆盖。
1150        let json = r#"[{
1151            "id": 1,
1152            "tag_name": "v1.0.0",
1153            "created_at": "2026-01-01 00:00:00"
1154        }]"#;
1155        let runner = MockCommandRunner::success(json);
1156        let provider = GitCodeReleaseProvider::with_runner("owner/repo", runner);
1157
1158        let err = provider
1159            .list(None)
1160            .await
1161            .expect_err("malformed created_at must still fail the whole list");
1162        // chrono 对非 RFC3339 时间戳给出的错误信息,经 serde_json 透传上来;
1163        // 钉住这条信息防止「null/缺失容错」被误扩展成「任意格式都容错」。
1164        assert!(
1165            err.to_string().contains("premature end of input"),
1166            "实际错误: {err}"
1167        );
1168    }
1169
1170    #[tokio::test]
1171    async fn test_should_cap_gitcode_release_per_page_at_api_maximum() {
1172        let runner = MockCommandRunner::success("[]");
1173        let provider = GitCodeReleaseProvider::with_runner("owner/repo", runner.clone());
1174
1175        provider.list(None).await.expect("list should succeed");
1176
1177        // 整串相等:`contains("per_page=100")` 在 per_page=1001 时同样为真,
1178        // 无法证明钳位生效。
1179        assert_eq!(
1180            runner.recorded_calls()[0].1,
1181            vec!["api", "/repos/owner/repo/releases?per_page=100&page=1"],
1182            "默认 cap={DEFAULT_LIST_LIMIT} 时 per_page 必须被 API 上限 100 钳住"
1183        );
1184    }
1185
1186    #[tokio::test]
1187    async fn test_should_create_release_successfully() {
1188        let runner = MockCommandRunner::success(valid_release_json());
1189        let provider = GitCodeReleaseProvider::with_runner("owner/repo", runner);
1190
1191        let release = provider
1192            .create(sample_release_args())
1193            .await
1194            .expect("create should succeed");
1195        assert_eq!(release.tag_name, "v1.0.0");
1196    }
1197
1198    #[tokio::test]
1199    async fn test_should_edit_release_successfully() {
1200        let runner = MockCommandRunner::success(valid_release_json());
1201        let provider = GitCodeReleaseProvider::with_runner("owner/repo", runner);
1202
1203        let release = provider
1204            .edit("v1.0.0", sample_release_args())
1205            .await
1206            .expect("edit should succeed");
1207        assert_eq!(release.tag_name, "v1.0.0");
1208    }
1209
1210    #[tokio::test]
1211    async fn test_should_delete_release_successfully() {
1212        let runner = MockCommandRunner::success("");
1213        let provider = GitCodeReleaseProvider::with_runner("owner/repo", runner);
1214
1215        assert!(provider.delete("v1.0.0").await.is_ok());
1216    }
1217
1218    #[tokio::test]
1219    async fn test_should_upload_asset_successfully() {
1220        let runner = MockCommandRunner::success("");
1221        let provider = GitCodeReleaseProvider::with_runner("owner/repo", runner);
1222
1223        assert!(
1224            provider
1225                .upload_asset("v1.0.0", "/tmp/artifact.tar.gz", "artifact.tar.gz")
1226                .await
1227                .is_ok()
1228        );
1229    }
1230}