Skip to main content

gitflow_gitcode/
pr.rs

1//! GitCode Pull Request 提供者实现。
2//!
3//! 通过 `gitcode` CLI 实现 [`PrProvider`] trait,支持 Pull Request 的创建、列表、查看、
4//! 关闭、合并、检出、草稿状态切换和分支同步。
5//! 所有方法通过 [`CommandRunner`] 调用 `gitcode` CLI,捕获 stdout 并解析 JSON。
6//! gitcode v0.6.x 的 JSON 架构(snake_case、`user` 键、嵌套 `head`/`base`)
7//! 与 `gh` 不同,统一经 `PrApiResponse` 映射为 core 的 [`PrData`]。
8
9use async_trait::async_trait;
10use chrono::{DateTime, Utc};
11use gitflow_core::{
12    CoreError, DEFAULT_LIST_LIMIT, FetchStrategy, Paged, Result, Session, fetch_capped,
13    pr::{CreatePrArgs, ListPrArgs, PrData, PrProvider},
14    types::{CommentData, MergeResult, MergeStrategy, State, UserSummary},
15};
16use serde::Deserialize;
17use tracing::debug;
18
19use crate::{
20    error::parse_gitcode_error,
21    runner::{CommandRunner, RealCommandRunner},
22};
23
24/// gitcode CLI v0.6.x `pr list/view/create --json` 的响应类型。
25///
26/// 字段命名与 `gh pr` 不同:snake_case、`user` 而非 `author`、
27/// 分支信息嵌套在 `head`/`base` 对象的 `ref` 字段、URL 为 `html_url`。
28/// 通过 [`From<PrApiResponse> for PrData`] 映射为 core 统一类型。
29#[derive(Debug, Clone, Deserialize)]
30struct PrApiResponse {
31    number: u64,
32    title: String,
33    #[serde(default)]
34    body: Option<String>,
35    #[serde(default)]
36    state: Option<String>,
37    #[serde(default)]
38    draft: bool,
39    #[serde(default)]
40    user: Option<PrUserApi>,
41    #[serde(default)]
42    head: Option<PrBranchApi>,
43    #[serde(default)]
44    base: Option<PrBranchApi>,
45    #[serde(default)]
46    created_at: Option<String>,
47    #[serde(default)]
48    updated_at: Option<String>,
49    /// GitCode API 若返回则用于区分"已合并"与"关闭未合并";
50    /// `state` 本身做不到(`merged` 与 `closed` 同样映射为 Closed)。
51    #[serde(default)]
52    merged_at: Option<String>,
53    #[serde(default)]
54    html_url: Option<String>,
55    #[serde(default)]
56    milestone: Option<PrMilestoneRefApi>,
57}
58
59/// 精简确认响应,`gitcode pr close --json` / `gitcode pr reopen --json` 实际返回的形状。
60///
61/// 与 `PrApiResponse`(`pr create`/`pr view` 的完整响应)不同——close/reopen
62/// 只返回一个状态确认对象,没有 `title` 等字段。实测响应(2026-09-21,对
63/// `byx-darwin/NexaTrade` 的真实 PR):
64/// `{"number":6,"state":"closed","owner":"byx-darwin","repo":"NexaTrade","url":"..."}`。
65/// 只需要 `number` 去调用 `view()` 拿完整数据,其余字段(`state`/`owner`/`repo`/`url`)
66/// 未被消费,故不建模,避免死代码;反序列化仍容忍它们出现在响应里(`serde_json`
67/// 默认忽略结构体未声明的字段)。
68#[derive(Debug, Clone, Deserialize)]
69struct PrCloseReopenApiResponse {
70    number: u64,
71}
72
73/// gitcode CLI 嵌入在 PR 响应中的 `milestone` 对象的最小字段集。
74///
75/// 与 `issue.rs` 的 `MilestoneRefApi` 同形(同一 GitCode API 端点复用同一
76/// milestone 序列化形状),单独定义以避免跨模块耦合。
77#[derive(Debug, Clone, Deserialize)]
78struct PrMilestoneRefApi {
79    number: u64,
80    title: String,
81}
82
83impl From<PrMilestoneRefApi> for gitflow_core::types::MilestoneRef {
84    fn from(api: PrMilestoneRefApi) -> Self {
85        Self {
86            number: api.number,
87            title: api.title,
88        }
89    }
90}
91
92/// gitcode PR JSON 中 `user` 对象的最小字段集。
93#[derive(Debug, Clone, Deserialize)]
94struct PrUserApi {
95    #[serde(default)]
96    login: String,
97    #[serde(default)]
98    id: Option<String>,
99}
100
101/// gitcode PR JSON 中 `head`/`base` 对象的最小字段集。
102#[derive(Debug, Clone, Deserialize)]
103struct PrBranchApi {
104    #[serde(default, rename = "ref")]
105    branch_ref: String,
106}
107
108/// gitcode CLI 评论响应类型,兼容两种已观测形态:
109/// - v0.6.x:`user` 为对象、`created_at` 为带偏移 RFC3339
110/// - 旧版本:`author` 为纯字符串、`created_at` 为 `YYYY-MM-DD HH:MM:SS`
111#[derive(Debug, Clone, Deserialize)]
112struct PrCommentApiResponse {
113    #[serde(deserialize_with = "gitflow_core::types::deserialize_u64_or_string")]
114    id: u64,
115    #[serde(default)]
116    body: String,
117    #[serde(default)]
118    author: Option<String>,
119    #[serde(default)]
120    user: Option<PrUserApi>,
121    #[serde(default)]
122    created_at: Option<String>,
123}
124
125impl From<PrCommentApiResponse> for CommentData {
126    fn from(api: PrCommentApiResponse) -> Self {
127        let author = api.user.map_or_else(
128            || UserSummary {
129                login: api.author.unwrap_or_else(|| "unknown".into()),
130                id: String::new(),
131            },
132            |u| UserSummary {
133                login: u.login,
134                id: u.id.unwrap_or_default(),
135            },
136        );
137        let created_at = api.created_at.as_deref().and_then(|s| {
138            DateTime::parse_from_rfc3339(s)
139                .map(|dt| dt.with_timezone(&Utc))
140                .or_else(|_| {
141                    chrono::NaiveDateTime::parse_from_str(s, "%Y-%m-%d %H:%M:%S")
142                        .map(|ndt| ndt.and_utc())
143                })
144                .ok()
145        });
146        Self {
147            id: api.id,
148            body: api.body,
149            author,
150            created_at,
151        }
152    }
153}
154
155impl From<PrApiResponse> for PrData {
156    fn from(api: PrApiResponse) -> Self {
157        // A missing timestamp stays None — never filled in as "now", which
158        // would misreport an unknown creation/update/merge time (#380).
159        let parse_time = |s: Option<String>| {
160            s.and_then(|v| DateTime::parse_from_rfc3339(&v).ok())
161                .map(|dt| dt.with_timezone(&Utc))
162        };
163        Self {
164            number: api.number,
165            title: api.title,
166            body: api.body,
167            state: match api.state.as_deref() {
168                Some("closed" | "merged") => State::Closed,
169                _ => State::Open,
170            },
171            draft: api.draft,
172            author: api.user.map_or(
173                UserSummary {
174                    login: "unknown".into(),
175                    id: String::new(),
176                },
177                |u| UserSummary {
178                    login: u.login,
179                    id: u.id.unwrap_or_default(),
180                },
181            ),
182            base_branch: api.base.map_or_else(String::new, |b| b.branch_ref),
183            head_branch: api.head.map_or_else(String::new, |h| h.branch_ref),
184            created_at: parse_time(api.created_at),
185            updated_at: parse_time(api.updated_at),
186            merged_at: parse_time(api.merged_at),
187            url: api.html_url.unwrap_or_default(),
188            milestone: api.milestone.map(Into::into),
189        }
190    }
191}
192
193/// GitCode Pull Request 提供者,通过 `gitcode` CLI 操作。
194///
195/// 该结构体通过调用 `gitcode` CLI 实现 [`PrProvider`] trait 的所有方法,
196/// 使上层命令能够以统一的方式操作 GitCode Pull Request。
197///
198/// 命令执行通过 [`CommandRunner`] 抽象,生产环境默认使用
199/// [`RealCommandRunner`],测试可注入自定义 runner 以模拟成功或失败场景。
200///
201/// # Examples
202///
203/// ```no_run
204/// use gitflow_gitcode::GitCodePrProvider;
205///
206/// let provider = GitCodePrProvider::new("octocat/hello-world");
207/// ```
208#[derive(Debug, Clone)]
209pub struct GitCodePrProvider<R: CommandRunner = RealCommandRunner> {
210    /// GitCode `owner/repo`,如 `"byx-darwin/gitflow-cli"`。
211    repo: String,
212    /// 用于执行 `gitcode` CLI 命令的 runner。
213    runner: R,
214}
215
216impl GitCodePrProvider<RealCommandRunner> {
217    /// 创建新的 GitCode Pull Request 提供者。
218    ///
219    /// `repo` 格式为 `owner/repo`。
220    #[must_use]
221    pub fn new(repo: impl Into<String>) -> Self {
222        Self {
223            repo: repo.into(),
224            runner: RealCommandRunner,
225        }
226    }
227
228    /// Create a new provider from a shared [`Session`].
229    ///
230    /// This enables state reuse across multiple operations in workflow chains.
231    #[must_use]
232    pub fn with_session(session: &Session) -> Self {
233        Self {
234            repo: session.repo.clone(),
235            runner: RealCommandRunner,
236        }
237    }
238}
239
240impl<R: CommandRunner> GitCodePrProvider<R> {
241    /// 使用自定义 [`CommandRunner`] 创建提供者。
242    ///
243    /// 主要用于测试,可注入模拟 runner 以控制 `gitcode` CLI 的输出。
244    /// `repo` 格式为 `owner/repo`。
245    #[must_use]
246    pub fn with_runner(repo: impl Into<String>, runner: R) -> Self {
247        Self {
248            repo: repo.into(),
249            runner,
250        }
251    }
252
253    /// [`PrProvider::list`] 的实际实现。
254    ///
255    /// 抽成普通(非 `async_trait` 装箱)的关联函数,避开泛型 `AsyncFn` 闭包
256    /// 在 `async_trait` 装箱 Future 内部触发的 HRTB `Send` 检查缺陷。
257    async fn list_impl(&self, args: ListPrArgs) -> Result<Paged<PrData>> {
258        let binary = crate::gitcode_binary();
259        let binary = &binary;
260        let cap = args.limit.unwrap_or(DEFAULT_LIST_LIMIT);
261        let repo = &self.repo;
262        let runner = &self.runner;
263        let state = args.state;
264        // 见 issue.rs 同处注释:`--per-page` 优先于 `--limit` 且被 API 封顶 100。
265        // 不用 gitcode 的 `--paginate`:那会让 CLI 自行取完全部页,本适配器
266        // 需要的是受控翻页以便 N+1 探测。
267        let per_page = cap.saturating_add(1).min(crate::GITCODE_API_MAX_PER_PAGE);
268
269        debug!(repo = %self.repo, cap, per_page, "spawning `gitcode pr list`");
270
271        fetch_capped(
272            FetchStrategy::Paged { per_page },
273            cap,
274            |page, per_page| async move {
275                let page_str = page.to_string();
276                let per_page_str = per_page.to_string();
277                let mut cmd_args: Vec<&str> = vec!["pr", "list", "--repo", repo, "--json"];
278
279                if let Some(state) = &state {
280                    cmd_args.push("--state");
281                    cmd_args.push(match state {
282                        State::Open => "open",
283                        State::Closed => "closed",
284                        State::All => "all",
285                    });
286                }
287
288                cmd_args.push("--per-page");
289                cmd_args.push(&per_page_str);
290                cmd_args.push("--page");
291                cmd_args.push(&page_str);
292
293                let output = runner
294                    .run(binary, &cmd_args)
295                    .await
296                    .map_err(|e| CoreError::Platform(format!("Failed to spawn gitcode: {e}")))?;
297
298                if !output.status.success() {
299                    return Err(parse_gitcode_error(&output.stderr).into());
300                }
301
302                let apis: Vec<PrApiResponse> =
303                    serde_json::from_slice(&output.stdout).map_err(CoreError::Serialization)?;
304
305                Ok(apis.into_iter().map(PrData::from).collect())
306            },
307        )
308        .await
309    }
310}
311
312#[async_trait]
313impl<R: CommandRunner + Clone + 'static> PrProvider for GitCodePrProvider<R> {
314    async fn create(&self, args: CreatePrArgs) -> Result<PrData> {
315        let binary = crate::gitcode_binary();
316        let repo = args.repo.as_deref().unwrap_or(&self.repo);
317        let mut cmd_args: Vec<&str> = vec![
318            "pr",
319            "create",
320            "--repo",
321            repo,
322            "--title",
323            &args.title,
324            "--head",
325            &args.head,
326            "--base",
327            &args.base,
328            "--json",
329        ];
330
331        let final_body =
332            gitflow_core::pr::format_closing_body(&args.body, &args.closes_issues, "Closes");
333
334        if let Some(body) = &final_body {
335            cmd_args.push("--body");
336            cmd_args.push(body);
337        }
338
339        if args.draft {
340            cmd_args.push("--draft");
341        }
342
343        debug!(
344            repo = %self.repo,
345            title = %args.title,
346            head = %args.head,
347            base = %args.base,
348            "spawning `gitcode pr create`"
349        );
350
351        let output = self
352            .runner
353            .run(&binary, &cmd_args)
354            .await
355            .map_err(|e| CoreError::Platform(format!("Failed to spawn gitcode: {e}")))?;
356
357        if !output.status.success() {
358            return Err(parse_gitcode_error(&output.stderr).into());
359        }
360
361        let api: PrApiResponse =
362            serde_json::from_slice(&output.stdout).map_err(CoreError::Serialization)?;
363
364        let mut pr_data: PrData = api.into();
365
366        // `gitcode pr create` has no `--milestone` flag at all (confirmed:
367        // `gitcode pr create --help`, 2026-09-21), so milestone attachment on
368        // creation is a create-then-edit two-step. A failure in the second
369        // step must not lose the already-created PR's data.
370        if let Some(identifier) = &args.milestone {
371            let milestone_provider =
372                crate::GitCodeMilestoneProvider::with_runner(repo, self.runner.clone());
373            let resolved =
374                gitflow_core::label::resolve_milestone_identifier(&milestone_provider, identifier)
375                    .await?;
376            let number_str = pr_data.number.to_string();
377            let milestone_number_str = resolved.number.to_string();
378
379            let edit_output = self
380                .runner
381                .run(
382                    &binary,
383                    &[
384                        "pr",
385                        "edit",
386                        &number_str,
387                        "--repo",
388                        repo,
389                        "--milestone",
390                        &milestone_number_str,
391                    ],
392                )
393                .await
394                .map_err(|e| {
395                    CoreError::Platform(format!(
396                        "PR #{} created, but attaching milestone failed to spawn: {e}",
397                        pr_data.number
398                    ))
399                })?;
400
401            if !edit_output.status.success() {
402                return Err(CoreError::Platform(format!(
403                    "PR #{} created, but attaching milestone failed: {}",
404                    pr_data.number,
405                    String::from_utf8_lossy(&edit_output.stderr)
406                )));
407            }
408
409            pr_data.milestone = Some(resolved);
410        }
411
412        Ok(pr_data)
413    }
414
415    async fn list(&self, args: ListPrArgs) -> Result<Paged<PrData>> {
416        self.list_impl(args).await
417    }
418
419    async fn view(&self, number: u64) -> Result<PrData> {
420        let binary = crate::gitcode_binary();
421        let number_str = number.to_string();
422        debug!(repo = %self.repo, number, "spawning `gitcode pr view`");
423
424        let output = self
425            .runner
426            .run(
427                &binary,
428                &["pr", "view", &number_str, "--repo", &self.repo, "--json"],
429            )
430            .await
431            .map_err(|e| CoreError::Platform(format!("Failed to spawn gitcode: {e}")))?;
432
433        if !output.status.success() {
434            return Err(parse_gitcode_error(&output.stderr).into());
435        }
436
437        let api: PrApiResponse =
438            serde_json::from_slice(&output.stdout).map_err(CoreError::Serialization)?;
439
440        Ok(api.into())
441    }
442
443    /// 关闭指定编号的 PR。
444    ///
445    /// 调用 `gitcode pr close <number> --repo <repo> --yes --json` 关闭 PR。
446    /// 该命令只返回精简确认对象(无 `title` 等字段),随后调用 [`Self::view`]
447    /// 取回更新后的完整 PR 数据。
448    ///
449    /// # Errors
450    ///
451    /// 当 PR 不存在、已关闭、`gitcode` CLI 调用失败,或关闭成功后 `view()`
452    /// 失败时返回错误。
453    async fn close(&self, number: u64) -> Result<PrData> {
454        let binary = crate::gitcode_binary();
455        let number_str = number.to_string();
456        debug!(repo = %self.repo, number, "spawning `gitcode pr close`");
457
458        let output = self
459            .runner
460            .run(
461                &binary,
462                &[
463                    "pr",
464                    "close",
465                    &number_str,
466                    "--repo",
467                    &self.repo,
468                    "--yes",
469                    "--json",
470                ],
471            )
472            .await
473            .map_err(|e| CoreError::Platform(format!("Failed to spawn gitcode: {e}")))?;
474
475        if !output.status.success() {
476            return Err(parse_gitcode_error(&output.stderr).into());
477        }
478
479        let close_result: PrCloseReopenApiResponse =
480            serde_json::from_slice(&output.stdout).map_err(CoreError::Serialization)?;
481
482        self.view(close_result.number).await
483    }
484
485    /// 重新打开指定编号的 PR。
486    ///
487    /// 调用 `gitcode pr reopen <number> --repo <repo> --yes --json` 重新打开已关闭的 PR。
488    /// 该命令只返回精简确认对象(无 `title` 等字段),随后调用 [`Self::view`]
489    /// 取回更新后的完整 PR 数据。
490    ///
491    /// # Errors
492    ///
493    /// 当 PR 不存在、未关闭、`gitcode` CLI 调用失败,或重新打开成功后 `view()`
494    /// 失败时返回错误。
495    async fn reopen(&self, number: u64) -> Result<PrData> {
496        let binary = crate::gitcode_binary();
497        let number_str = number.to_string();
498        debug!(repo = %self.repo, number, "spawning `gitcode pr reopen`");
499
500        let output = self
501            .runner
502            .run(
503                &binary,
504                &[
505                    "pr",
506                    "reopen",
507                    &number_str,
508                    "--repo",
509                    &self.repo,
510                    "--yes",
511                    "--json",
512                ],
513            )
514            .await
515            .map_err(|e| CoreError::Platform(format!("Failed to spawn gitcode: {e}")))?;
516
517        if !output.status.success() {
518            return Err(parse_gitcode_error(&output.stderr).into());
519        }
520
521        let reopen_result: PrCloseReopenApiResponse =
522            serde_json::from_slice(&output.stdout).map_err(CoreError::Serialization)?;
523
524        self.view(reopen_result.number).await
525    }
526
527    /// 在指定 PR 上添加评论。
528    ///
529    /// 调用 `gitcode pr comment <number> --repo <repo> --body "<body>" --json`
530    /// 发布评论,并返回新建评论的数据。
531    ///
532    /// # Errors
533    ///
534    /// 当 PR 不存在、`body` 为空或 `gitcode` CLI 调用失败时返回错误。
535    async fn comment(&self, number: u64, body: &str) -> Result<CommentData> {
536        let binary = crate::gitcode_binary();
537        let number_str = number.to_string();
538        debug!(repo = %self.repo, number, "spawning `gitcode pr comment`");
539
540        let output = self
541            .runner
542            .run(
543                &binary,
544                &[
545                    "pr",
546                    "comment",
547                    &number_str,
548                    "--repo",
549                    &self.repo,
550                    "--body",
551                    body,
552                    "--json",
553                ],
554            )
555            .await
556            .map_err(|e| CoreError::Platform(format!("Failed to spawn gitcode: {e}")))?;
557
558        if !output.status.success() {
559            return Err(parse_gitcode_error(&output.stderr).into());
560        }
561
562        let api: PrCommentApiResponse =
563            serde_json::from_slice(&output.stdout).map_err(CoreError::Serialization)?;
564
565        Ok(api.into())
566    }
567
568    /// 合并指定编号的 PR。
569    ///
570    /// 调用 `gitcode pr merge <number> --repo <repo> --yes [--method <strategy>]`
571    /// 合并 PR。`strategy` 映射到 gitcode 的 `--method` 参数
572    ///(`merge` / `squash` / `rebase`);未指定时使用平台默认策略。
573    ///
574    /// GitCode CLI 无排队合并语义,`auto = true` 直接报错而非静默退化成
575    /// 立即合并——否则调用方会以为合并已被 CI 把关。
576    ///
577    /// # Errors
578    ///
579    /// 当 PR 不存在、存在冲突无法合并、请求了 `auto` 或 `gitcode` CLI 调用失败时返回错误。
580    async fn merge(
581        &self,
582        number: u64,
583        strategy: Option<MergeStrategy>,
584        auto: bool,
585    ) -> Result<MergeResult> {
586        if auto {
587            return Err(CoreError::Platform(
588                "GitCode CLI 不支持排队合并(auto)。请改用 GitHub/GitLab,或在 CI \
589                 通过后手动合并。"
590                    .into(),
591            ));
592        }
593
594        let binary = crate::gitcode_binary();
595        let number_str = number.to_string();
596        let mut cmd_args: Vec<&str> =
597            vec!["pr", "merge", &number_str, "--repo", &self.repo, "--yes"];
598
599        let strategy_value;
600        if let Some(strategy) = strategy {
601            strategy_value = match strategy {
602                MergeStrategy::Merge => "merge",
603                MergeStrategy::Squash => "squash",
604                MergeStrategy::Rebase => "rebase",
605            };
606            cmd_args.push("--method");
607            cmd_args.push(strategy_value);
608        }
609
610        debug!(repo = %self.repo, number, ?strategy, "spawning `gitcode pr merge`");
611
612        let output = self
613            .runner
614            .run(&binary, &cmd_args)
615            .await
616            .map_err(|e| CoreError::Platform(format!("Failed to spawn gitcode: {e}")))?;
617
618        if !output.status.success() {
619            return Err(parse_gitcode_error(&output.stderr).into());
620        }
621
622        // `gitcode pr merge` outputs a human-readable message, not JSON.
623        let message = String::from_utf8_lossy(&output.stdout).trim().to_string();
624        Ok(MergeResult {
625            merged: true,
626            sha: None,
627            message: Some(message),
628        })
629    }
630
631    /// 在本地检出指定 PR 的分支。
632    ///
633    /// 调用 `gc pr checkout <number> --repo <repo>` 在本地工作区创建并切换到
634    /// PR 的来源分支。如果本地已存在该分支,则尝试更新它。
635    ///
636    /// # Errors
637    ///
638    /// 当 PR 不存在、本地 git 操作失败或 `gitcode` CLI 调用失败时返回错误。
639    async fn checkout(&self, number: u64) -> Result<()> {
640        let binary = crate::gitcode_binary();
641        let number_str = number.to_string();
642        debug!(repo = %self.repo, number, "spawning `gc pr checkout`");
643
644        let output = self
645            .runner
646            .run(
647                &binary,
648                &["pr", "checkout", &number_str, "--repo", &self.repo],
649            )
650            .await
651            .map_err(|e| CoreError::Platform(format!("Failed to spawn gitcode: {e}")))?;
652
653        if !output.status.success() {
654            return Err(parse_gitcode_error(&output.stderr).into());
655        }
656
657        Ok(())
658    }
659
660    /// 将草稿 PR 标记为可审查状态(ready for review)。
661    ///
662    /// 调用 `gc pr ready <number> --repo <repo>` 将草稿 PR 转为可审查状态,
663    /// 并通过 `gc pr view` 重新获取更新后的 PR 数据。
664    ///
665    /// # Errors
666    ///
667    /// 当 PR 不存在、不是草稿状态或 `gitcode` CLI 调用失败时返回错误。
668    async fn mark_ready(&self, number: u64) -> Result<PrData> {
669        let binary = crate::gitcode_binary();
670        let number_str = number.to_string();
671        debug!(repo = %self.repo, number, "spawning `gc pr ready`");
672
673        let output = self
674            .runner
675            .run(&binary, &["pr", "ready", &number_str, "--repo", &self.repo])
676            .await
677            .map_err(|e| CoreError::Platform(format!("Failed to spawn gitcode: {e}")))?;
678
679        if !output.status.success() {
680            return Err(parse_gitcode_error(&output.stderr).into());
681        }
682
683        // `gc pr ready` does not return JSON; re-fetch the PR to get updated data.
684        self.view(number).await
685    }
686
687    /// 将 PR 标记为草稿状态(work in progress)。
688    ///
689    /// 调用 `gc pr convert-to-draft <number> --repo <repo>` 将可审查的 PR 转为草稿,
690    /// 并通过 `gc pr view` 重新获取更新后的 PR 数据。
691    ///
692    /// # Errors
693    ///
694    /// 当 PR 不存在、已是草稿状态或 `gitcode` CLI 调用失败时返回错误。
695    async fn mark_wip(&self, number: u64) -> Result<PrData> {
696        let binary = crate::gitcode_binary();
697        let number_str = number.to_string();
698        debug!(repo = %self.repo, number, "spawning `gc pr convert-to-draft`");
699
700        let output = self
701            .runner
702            .run(
703                &binary,
704                &["pr", "convert-to-draft", &number_str, "--repo", &self.repo],
705            )
706            .await
707            .map_err(|e| CoreError::Platform(format!("Failed to spawn gitcode: {e}")))?;
708
709        if !output.status.success() {
710            return Err(parse_gitcode_error(&output.stderr).into());
711        }
712
713        // `gc pr convert-to-draft` does not return JSON; re-fetch the PR.
714        self.view(number).await
715    }
716
717    /// 同步 PR 的分支(将 base 分支的最新变更合入 head 分支)。
718    ///
719    /// 调用 `gc pr update-branch <number> --repo <repo>` 将 PR 的来源分支
720    /// 更新到与目标分支的最新状态同步,解决分支过时问题。
721    ///
722    /// # Errors
723    ///
724    /// 当 PR 不存在、同步存在冲突或 `gitcode` CLI 调用失败时返回错误。
725    async fn sync_branch(&self, number: u64) -> Result<()> {
726        let binary = crate::gitcode_binary();
727        let number_str = number.to_string();
728        debug!(repo = %self.repo, number, "spawning `gc pr update-branch`");
729
730        let output = self
731            .runner
732            .run(
733                &binary,
734                &["pr", "update-branch", &number_str, "--repo", &self.repo],
735            )
736            .await
737            .map_err(|e| CoreError::Platform(format!("Failed to spawn gitcode: {e}")))?;
738
739        if !output.status.success() {
740            return Err(parse_gitcode_error(&output.stderr).into());
741        }
742
743        Ok(())
744    }
745
746    /// 获取指定 PR 的统一差异格式(unified diff)文本。
747    ///
748    /// 调用 `gc mr diff <number> -R <repo>` 获取平台原生的 diff 输出,
749    /// 可直接用于 `git apply`。
750    ///
751    /// # Errors
752    ///
753    /// 当 PR 不存在或 `gitcode` CLI 调用失败时返回错误。
754    async fn diff(&self, number: u64) -> Result<String> {
755        let binary = crate::gitcode_binary();
756        let number_str = number.to_string();
757        debug!(repo = %self.repo, number, "spawning `gc mr diff`");
758
759        let output = self
760            .runner
761            .run(&binary, &["mr", "diff", &number_str, "-R", &self.repo])
762            .await
763            .map_err(|e| CoreError::Platform(format!("Failed to spawn gitcode mr diff: {e}")))?;
764
765        if !output.status.success() {
766            return Err(parse_gitcode_error(&output.stderr).into());
767        }
768
769        Ok(String::from_utf8_lossy(&output.stdout).into_owned())
770    }
771
772    /// 获取指定 PR 的 patch 格式文本(含邮件头信息)。
773    ///
774    /// 调用 `gc mr patch <number> -R <repo>` 获取包含 commit 元数据的
775    /// patch 格式输出,可用于 `git am`。
776    ///
777    /// # Errors
778    ///
779    /// 当 PR 不存在或 `gitcode` CLI 调用失败时返回错误。
780    async fn patch(&self, number: u64) -> Result<String> {
781        let binary = crate::gitcode_binary();
782        let number_str = number.to_string();
783        debug!(repo = %self.repo, number, "spawning `gc mr patch`");
784
785        let output = self
786            .runner
787            .run(&binary, &["mr", "patch", &number_str, "-R", &self.repo])
788            .await
789            .map_err(|e| CoreError::Platform(format!("Failed to spawn gitcode mr patch: {e}")))?;
790
791        if !output.status.success() {
792            return Err(parse_gitcode_error(&output.stderr).into());
793        }
794
795        Ok(String::from_utf8_lossy(&output.stdout).into_owned())
796    }
797
798    /// 查询仓库配置的默认分支。
799    ///
800    /// GitCode CLI 无对应查询能力(先例:`merge --auto`),直接返回
801    /// [`CoreError::Platform`],不发起任何 CLI 调用。
802    ///
803    /// # Errors
804    ///
805    /// 恒定返回错误:GitCode 平台不支持此查询。
806    async fn default_branch(&self) -> Result<String> {
807        Err(CoreError::Platform(
808            "GitCode CLI 不支持查询仓库默认分支。请显式传入 --base,或改用 GitHub/GitLab。".into(),
809        ))
810    }
811}
812
813#[cfg(test)]
814mod tests {
815    use super::*;
816    use crate::runner::{MockCommandRunner, SequencedMockCommandRunner};
817
818    /// gitcode CLI v0.6.1 `pr list/view --json` 的真实输出结构(2026-07-31 实测捕获,已精简)。
819    fn real_gitcode_pr_json() -> &'static str {
820        r###"{
821            "id": 8957463,
822            "number": 52,
823            "title": "test(badge): 引擎规则函数测试覆盖",
824            "body": "## Summary\n\nCloses #88",
825            "description": "## Summary\n\nCloses #88",
826            "state": "merged",
827            "html_url": "https://gitcode.com/byx-darwin/go-beniofit/merge_requests/52",
828            "diff_url": "",
829            "patch_url": "",
830            "draft": false,
831            "merged": true,
832            "merged_at": "2026-07-30T13:23:13+08:00",
833            "created_at": "2026-07-30T12:40:46+08:00",
834            "updated_at": "2026-07-30T13:23:13+08:00",
835            "user": {
836                "id": "66767cd4096c81780c61bf07",
837                "login": "byx-darwin",
838                "name": "baoyx",
839                "email": "",
840                "avatar_url": "https://cdn-img.gitcode.com/avatar.png",
841                "html_url": "https://gitcode.com/byx-darwin",
842                "created_at": ""
843            },
844            "head": {
845                "label": "test/88-engine-rule-coverage",
846                "ref": "test/88-engine-rule-coverage",
847                "sha": "8f1d3f31d7ee598a16f40fcac55b86154122c93c"
848            },
849            "base": {
850                "label": "master",
851                "ref": "master",
852                "sha": "bba7d724c8c73531acf1dca5f639b2a273c26eae"
853            },
854            "labels": [],
855            "assignees": [],
856            "additions": 120,
857            "deletions": 3,
858            "changed_files": 1,
859            "commits": 2,
860            "comments": 0,
861            "mergeable": true,
862            "mergeable_state": "can_be_merged",
863            "milestone": null,
864            "closed_at": "2026-07-30T13:23:13+08:00",
865            "requested_reviewers": []
866        }"###
867    }
868
869    #[test]
870    fn test_should_map_real_gitcode_pr_response_to_pr_data() {
871        let api: PrApiResponse =
872            serde_json::from_str(real_gitcode_pr_json()).expect(r"valid gitcode v0.6.1 PR JSON");
873        let pr: PrData = api.into();
874
875        assert_eq!(pr.number, 52);
876        assert_eq!(pr.title, r"test(badge): 引擎规则函数测试覆盖");
877        assert_eq!(pr.state, State::Closed, r"merged 必须映射为 Closed");
878        assert!(!pr.draft);
879        assert_eq!(pr.author.login, "byx-darwin");
880        assert_eq!(pr.author.id, "66767cd4096c81780c61bf07");
881        assert_eq!(pr.base_branch, "master");
882        assert_eq!(pr.head_branch, "test/88-engine-rule-coverage");
883        assert_eq!(
884            pr.url,
885            "https://gitcode.com/byx-darwin/go-beniofit/merge_requests/52"
886        );
887        assert_eq!(
888            pr.created_at.map(|dt| dt.to_rfc3339()),
889            Some("2026-07-30T04:40:46+00:00".to_string())
890        );
891    }
892
893    #[test]
894    fn test_should_map_open_pr_with_minimal_gitcode_fields() {
895        let json = r#"{
896            "id": 1,
897            "number": 7,
898            "title": "New work",
899            "state": "open",
900            "html_url": "https://gitcode.com/o/r/merge_requests/7",
901            "draft": true,
902            "user": {"id": "u1", "login": "dev"},
903            "head": {"ref": "feature/x"},
904            "base": {"ref": "main"}
905        }"#;
906        let api: PrApiResponse = serde_json::from_str(json).expect(r"minimal gitcode PR JSON");
907        let pr: PrData = api.into();
908
909        assert_eq!(pr.state, State::Open);
910        assert!(pr.draft);
911        assert_eq!(pr.body, None);
912        assert_eq!(pr.head_branch, "feature/x");
913        assert_eq!(pr.base_branch, "main");
914        assert_eq!(pr.author.login, "dev");
915        assert!(
916            pr.created_at.is_none(),
917            "missing created_at must stay None, not fall back to Utc::now()"
918        );
919        assert!(
920            pr.updated_at.is_none(),
921            "missing updated_at must stay None, not fall back to Utc::now()"
922        );
923    }
924
925    #[test]
926    fn test_should_construct_gitcode_pr_provider() {
927        let provider = GitCodePrProvider::new("octocat/hello-world");
928        assert_eq!(provider.repo, "octocat/hello-world");
929    }
930
931    #[test]
932    fn test_should_construct_gitcode_pr_provider_from_string() {
933        let repo = String::from("octocat/hello-world");
934        let provider = GitCodePrProvider::new(repo);
935        assert_eq!(provider.repo, "octocat/hello-world");
936    }
937
938    #[test]
939    fn test_should_deserialize_empty_pr_list_from_gc_output() {
940        let gc_json = b"[]";
941        let prs: Vec<PrData> = serde_json::from_slice(gc_json).expect("valid PrData list");
942        assert!(prs.is_empty());
943    }
944
945    #[test]
946    fn test_should_debug_format_provider() {
947        let provider = GitCodePrProvider::new("octocat/hello-world");
948        let debug = format!("{provider:?}");
949        assert!(debug.contains("GitCodePrProvider"));
950        assert!(debug.contains("octocat/hello-world"));
951    }
952
953    #[test]
954    fn test_should_deserialize_comment_data_from_gc_pr_comment_output() {
955        let gc_json = br#"{
956            "id": 2002,
957            "body": "Approved, merging now.",
958            "author": {"login": "reviewer", "id": "88"},
959            "createdAt": "2026-06-20T16:00:00Z"
960        }"#;
961
962        let comment: CommentData = serde_json::from_slice(gc_json).expect("valid CommentData");
963        assert_eq!(comment.id, 2002);
964        assert_eq!(comment.body, "Approved, merging now.");
965        assert_eq!(comment.author.login, "reviewer");
966        assert_eq!(comment.author.id, "88");
967    }
968
969    #[test]
970    fn test_should_keep_pr_comment_created_at_none_when_gc_api_omits_it() {
971        let gc_json = br#"{
972            "id": 2003,
973            "body": "No timestamp provided.",
974            "user": {"login": "reviewer", "id": "88"}
975        }"#;
976
977        let api: PrCommentApiResponse =
978            serde_json::from_slice(gc_json).expect("valid PrCommentApiResponse");
979        let comment = CommentData::from(api);
980        assert!(
981            comment.created_at.is_none(),
982            "missing created_at must stay None, not fall back to Utc::now()"
983        );
984    }
985
986    #[test]
987    fn test_should_deserialize_merge_result_from_gc_merge_output() {
988        let gc_text = b"Pull request #123 was successfully merged.\n";
989        let message = String::from_utf8_lossy(gc_text).trim().to_string();
990        let result = MergeResult {
991            merged: true,
992            sha: None,
993            message: Some(message),
994        };
995
996        assert!(result.merged);
997        assert!(result.message.as_deref().is_some());
998        assert_eq!(
999            result.message.as_deref(),
1000            Some("Pull request #123 was successfully merged.")
1001        );
1002    }
1003
1004    #[test]
1005    fn test_should_roundtrip_merge_result_via_serde() {
1006        let result = MergeResult {
1007            merged: true,
1008            sha: Some("deadbeef1234".into()),
1009            message: Some("Squash merged".into()),
1010        };
1011        let json = serde_json::to_string(&result).expect("serialize");
1012        let round_tripped: MergeResult = serde_json::from_str(&json).expect("deserialize");
1013        assert!(round_tripped.merged);
1014        assert_eq!(round_tripped.sha, result.sha);
1015        assert_eq!(round_tripped.message, result.message);
1016    }
1017
1018    #[test]
1019    fn test_should_serialize_merge_result_skips_null_fields() {
1020        let result = MergeResult {
1021            merged: false,
1022            sha: None,
1023            message: None,
1024        };
1025        let json = serde_json::to_string(&result).expect("serialize");
1026        assert!(!json.contains("null"));
1027        assert_eq!(json, r#"{"merged":false}"#);
1028    }
1029
1030    #[test]
1031    fn test_should_create_provider_with_different_repos() {
1032        let r1 = GitCodePrProvider::new("org/repo-a");
1033        let r2 = GitCodePrProvider::new("org/repo-b");
1034        assert_eq!(r1.repo, "org/repo-a");
1035        assert_eq!(r2.repo, "org/repo-b");
1036    }
1037
1038    #[test]
1039    fn test_should_clone_gitcode_pr_provider() {
1040        let original = GitCodePrProvider::new("owner/repo");
1041        let cloned = original.clone();
1042        assert_eq!(original.repo, cloned.repo);
1043    }
1044
1045    // --- Failure-path tests using an injected MockCommandRunner ---
1046
1047    fn sample_create_args() -> CreatePrArgs {
1048        CreatePrArgs {
1049            title: "New feature".to_string(),
1050            body: Some("Adds a feature".to_string()),
1051            head: "feature/x".to_string(),
1052            base: "main".to_string(),
1053            draft: false,
1054            repo: None,
1055            closes_issues: vec![],
1056            milestone: None,
1057        }
1058    }
1059
1060    #[test]
1061    fn test_should_format_gitcode_body_with_closing_issues() {
1062        use gitflow_core::pr::format_closing_body;
1063
1064        let body = Some("PR description".to_string());
1065        let issues = vec![10u64, 11];
1066        let result = format_closing_body(&body, &issues, "Closes");
1067        assert_eq!(
1068            result,
1069            Some("PR description\n\nCloses #10\nCloses #11".to_string())
1070        );
1071    }
1072
1073    #[tokio::test]
1074    async fn test_should_return_platform_error_when_gc_fails_for_create() {
1075        let runner = MockCommandRunner::failure("validation failed", 256);
1076        let provider = GitCodePrProvider::with_runner("owner/repo", runner);
1077
1078        let result = provider.create(sample_create_args()).await;
1079
1080        assert!(matches!(
1081            result.unwrap_err(),
1082            gitflow_core::CoreError::Cli(_)
1083        ));
1084    }
1085
1086    #[tokio::test]
1087    async fn test_should_return_serialization_error_on_invalid_json_for_create() {
1088        let runner = MockCommandRunner::success("not valid json");
1089        let provider = GitCodePrProvider::with_runner("owner/repo", runner);
1090
1091        let result = provider.create(sample_create_args()).await;
1092
1093        assert!(matches!(
1094            result.unwrap_err(),
1095            gitflow_core::CoreError::Serialization(_)
1096        ));
1097    }
1098
1099    // --- milestone wiring: create+edit two-step ---
1100
1101    /// A single-item `gitcode milestone list --json` response resolving to
1102    /// number 3 / title "v2.0", matching `resolve_milestone_identifier`'s contract.
1103    fn pr_milestone_list_fixture() -> String {
1104        r#"[{"number": 3, "title": "v2.0", "description": null, "state": "open", "due_on": null, "closed_issues": 0, "open_issues": 0}]"#.to_string()
1105    }
1106
1107    #[tokio::test]
1108    async fn test_should_attach_milestone_via_create_then_edit_two_step() {
1109        // `gitcode pr create` has no `--milestone` flag, so attaching a
1110        // milestone on creation is: 1. `pr create` (no milestone), 2. resolve
1111        // the identifier via `gitcode milestone list`, 3. `pr edit --milestone <number>`.
1112        let runner = SequencedMockCommandRunner::from_results(&[
1113            (
1114                true,
1115                r#"{"number":52,"title":"Add feature","body":null,"state":"open","draft":false,"user":{"login":"alice","id":"2"},"head":{"ref":"feature/x"},"base":{"ref":"main"},"created_at":"2026-02-20T14:00:00Z","updated_at":"2026-02-20T14:00:00Z","html_url":"https://gitcode.com/owner/repo/merge_requests/52"}"#,
1116            ),
1117            (true, &pr_milestone_list_fixture()),
1118            (true, ""),
1119        ]);
1120        let provider = GitCodePrProvider::with_runner("owner/repo", runner.clone());
1121
1122        let mut args = sample_create_args();
1123        args.milestone = Some("3".to_string());
1124
1125        let pr = provider.create(args).await.expect("create should succeed");
1126
1127        assert_eq!(pr.number, 52);
1128        assert_eq!(
1129            pr.milestone,
1130            Some(gitflow_core::types::MilestoneRef {
1131                number: 3,
1132                title: "v2.0".into()
1133            })
1134        );
1135
1136        let calls = runner.recorded_calls();
1137        assert_eq!(
1138            calls.len(),
1139            3,
1140            "must call: pr create, milestone list, pr edit"
1141        );
1142        assert_eq!(calls[0].1[0], "pr");
1143        assert_eq!(calls[0].1[1], "create");
1144        assert!(
1145            !calls[0].1.iter().any(|a| a == "--milestone"),
1146            "pr create has no --milestone flag; must not be passed, got: {:?}",
1147            calls[0].1
1148        );
1149        assert_eq!(
1150            calls[1].1.first().map(String::as_str),
1151            Some("milestone"),
1152            "second call must resolve the milestone via `gitcode milestone list`, got: {:?}",
1153            calls[1].1
1154        );
1155        let edit_call = &calls[2].1;
1156        assert_eq!(edit_call[0], "pr");
1157        assert_eq!(edit_call[1], "edit");
1158        assert_eq!(edit_call[2], "52");
1159        assert!(
1160            edit_call
1161                .windows(2)
1162                .any(|w| w[0] == "--milestone" && w[1] == "3"),
1163            "pr edit argv must carry the resolved milestone NUMBER, got: {edit_call:?}"
1164        );
1165    }
1166
1167    #[tokio::test]
1168    async fn test_should_resolve_milestone_against_overridden_repo_on_pr_create() {
1169        // Regression: `args.repo` overrides the target repo for both `pr
1170        // create` and `pr edit`, but milestone resolution must ALSO target
1171        // that overridden repo, not the provider's default `self.repo`.
1172        let runner = SequencedMockCommandRunner::from_results(&[
1173            (
1174                true,
1175                r#"{"number":52,"title":"Add feature","body":null,"state":"open","draft":false,"user":{"login":"alice","id":"2"},"head":{"ref":"feature/x"},"base":{"ref":"main"},"created_at":"2026-02-20T14:00:00Z","updated_at":"2026-02-20T14:00:00Z","html_url":"https://gitcode.com/other/repo/merge_requests/52"}"#,
1176            ),
1177            (true, &pr_milestone_list_fixture()),
1178            (true, ""),
1179        ]);
1180        let provider = GitCodePrProvider::with_runner("owner/repo", runner.clone());
1181
1182        let mut args = sample_create_args();
1183        args.repo = Some("other/repo".to_string());
1184        args.milestone = Some("3".to_string());
1185
1186        let pr = provider.create(args).await.expect("create should succeed");
1187        assert_eq!(
1188            pr.milestone,
1189            Some(gitflow_core::types::MilestoneRef {
1190                number: 3,
1191                title: "v2.0".into()
1192            })
1193        );
1194
1195        let calls = runner.recorded_calls();
1196        assert_eq!(
1197            calls.len(),
1198            3,
1199            "must call: pr create, milestone list, pr edit"
1200        );
1201
1202        let create_call = &calls[0].1;
1203        assert!(
1204            create_call
1205                .windows(2)
1206                .any(|w| w[0] == "--repo" && w[1] == "other/repo"),
1207            "pr create must target the overridden repo, got: {create_call:?}"
1208        );
1209
1210        let milestone_list_call = &calls[1].1;
1211        assert!(
1212            milestone_list_call
1213                .windows(2)
1214                .any(|w| w[0] == "-R" && w[1] == "other/repo"),
1215            "milestone resolution must target the overridden repo (\"other/repo\"), not the \
1216             provider default (\"owner/repo\"), got: {milestone_list_call:?}"
1217        );
1218
1219        let edit_call = &calls[2].1;
1220        assert!(
1221            edit_call
1222                .windows(2)
1223                .any(|w| w[0] == "--repo" && w[1] == "other/repo"),
1224            "pr edit must target the overridden repo, got: {edit_call:?}"
1225        );
1226    }
1227
1228    #[tokio::test]
1229    async fn test_should_surface_created_pr_number_when_milestone_attach_fails_to_spawn() {
1230        let runner = SequencedMockCommandRunner::from_results(&[
1231            (
1232                true,
1233                r#"{"number":52,"title":"Add feature","body":null,"state":"open","draft":false,"user":{"login":"alice","id":"2"},"head":{"ref":"feature/x"},"base":{"ref":"main"},"created_at":"2026-02-20T14:00:00Z","updated_at":"2026-02-20T14:00:00Z","html_url":"https://gitcode.com/owner/repo/merge_requests/52"}"#,
1234            ),
1235            (true, &pr_milestone_list_fixture()),
1236            (false, "gitcode: 403 Forbidden"),
1237        ]);
1238        let provider = GitCodePrProvider::with_runner("owner/repo", runner);
1239
1240        let mut args = sample_create_args();
1241        args.milestone = Some("3".to_string());
1242
1243        let err = provider
1244            .create(args)
1245            .await
1246            .expect_err("milestone attach failure must surface, not be swallowed");
1247
1248        let msg = format!("{err}");
1249        assert!(
1250            matches!(err, gitflow_core::CoreError::Platform(_)),
1251            "expected CoreError::Platform, got {msg}"
1252        );
1253        assert!(
1254            msg.contains("52"),
1255            "error must name the already-created PR number, got: {msg}"
1256        );
1257        assert!(
1258            msg.contains("milestone"),
1259            "error must mention milestone attachment, got: {msg}"
1260        );
1261    }
1262
1263    #[tokio::test]
1264    async fn test_should_propagate_error_when_milestone_identifier_not_found_on_pr_create_two_step()
1265    {
1266        let runner = SequencedMockCommandRunner::from_results(&[
1267            (
1268                true,
1269                r#"{"number":52,"title":"Add feature","body":null,"state":"open","draft":false,"user":{"login":"alice","id":"2"},"head":{"ref":"feature/x"},"base":{"ref":"main"},"created_at":"2026-02-20T14:00:00Z","updated_at":"2026-02-20T14:00:00Z","html_url":"https://gitcode.com/owner/repo/merge_requests/52"}"#,
1270            ),
1271            (true, "[]"),
1272        ]);
1273        let provider = GitCodePrProvider::with_runner("owner/repo", runner);
1274
1275        let mut args = sample_create_args();
1276        args.milestone = Some("does-not-exist".to_string());
1277
1278        let result = provider.create(args).await;
1279        assert!(result.is_err());
1280    }
1281
1282    #[tokio::test]
1283    async fn test_should_return_platform_error_when_gc_fails_for_list() {
1284        let runner = MockCommandRunner::failure("forbidden", 256);
1285        let provider = GitCodePrProvider::with_runner("owner/repo", runner);
1286
1287        let result = provider.list(ListPrArgs::default()).await;
1288
1289        assert!(matches!(
1290            result.unwrap_err(),
1291            gitflow_core::CoreError::Cli(_)
1292        ));
1293    }
1294
1295    #[tokio::test]
1296    async fn test_should_return_serialization_error_on_invalid_json_for_list() {
1297        let runner = MockCommandRunner::success("invalid");
1298        let provider = GitCodePrProvider::with_runner("owner/repo", runner);
1299
1300        let result = provider.list(ListPrArgs::default()).await;
1301
1302        assert!(matches!(
1303            result.unwrap_err(),
1304            gitflow_core::CoreError::Serialization(_)
1305        ));
1306    }
1307
1308    #[tokio::test]
1309    async fn test_should_page_through_gitcode_pr_list_with_incrementing_page_numbers() {
1310        // cap=100 → per_page=100,want=101。首页满 100 条 ⇒ 必然发出第二页。
1311        // cap 必须 ≥ 100:更小的 cap 会让 per_page 恰为 cap+1,首页一次满足
1312        // want,循环只发一次调用,页号递增无从观测。
1313        let one = real_gitcode_pr_json();
1314        let page = format!("[{}]", vec![one; 100].join(","));
1315        let runner = SequencedMockCommandRunner::from_results(&[(true, &page), (true, &page)]);
1316        let provider = GitCodePrProvider::with_runner("owner/repo", runner.clone());
1317
1318        let paged = provider
1319            .list(ListPrArgs {
1320                state: Some(State::Open),
1321                limit: Some(100),
1322            })
1323            .await
1324            .expect("list should succeed");
1325
1326        assert_eq!(paged.items.len(), 100);
1327        assert!(paged.truncated);
1328
1329        let calls = runner.recorded_calls();
1330        assert_eq!(
1331            calls.len(),
1332            2,
1333            "必须真的翻到第二页,实际调用数: {}",
1334            calls.len()
1335        );
1336        let first = &calls[0].1;
1337        assert!(
1338            first
1339                .windows(2)
1340                .any(|w| w[0] == "--per-page" && w[1] == "100"),
1341            "实际 argv: {first:?}"
1342        );
1343        assert!(
1344            first.windows(2).any(|w| w[0] == "--page" && w[1] == "1"),
1345            "实际 argv: {first:?}"
1346        );
1347        assert!(
1348            !first.iter().any(|a| a == "--limit"),
1349            "实际 argv: {first:?}"
1350        );
1351        assert!(
1352            calls[1]
1353                .1
1354                .windows(2)
1355                .any(|w| w[0] == "--page" && w[1] == "2"),
1356            "页号必须递增,实际 argv: {:?}",
1357            calls[1].1
1358        );
1359    }
1360
1361    #[tokio::test]
1362    async fn test_should_produce_complete_argv_for_gitcode_pr_list_with_state() {
1363        let runner = MockCommandRunner::success("[]");
1364        let provider = GitCodePrProvider::with_runner("owner/repo", runner.clone());
1365        let args = ListPrArgs {
1366            state: Some(State::Open),
1367            ..ListPrArgs::default()
1368        };
1369        provider.list(args).await.expect("list should succeed");
1370        assert_eq!(
1371            runner.recorded_calls()[0].1,
1372            vec![
1373                "pr",
1374                "list",
1375                "--repo",
1376                "owner/repo",
1377                "--json",
1378                "--state",
1379                "open",
1380                "--per-page",
1381                "100",
1382                "--page",
1383                "1",
1384            ]
1385        );
1386    }
1387
1388    #[tokio::test]
1389    async fn test_should_return_platform_error_when_gc_fails_for_view() {
1390        let runner = MockCommandRunner::failure("pr not found", 256);
1391        let provider = GitCodePrProvider::with_runner("owner/repo", runner);
1392
1393        let result = provider.view(999).await;
1394
1395        assert!(matches!(
1396            result.unwrap_err(),
1397            gitflow_core::CoreError::Cli(_)
1398        ));
1399    }
1400
1401    #[tokio::test]
1402    async fn test_should_return_serialization_error_on_invalid_json_for_view() {
1403        let runner = MockCommandRunner::success("not valid json");
1404        let provider = GitCodePrProvider::with_runner("owner/repo", runner);
1405
1406        let result = provider.view(1).await;
1407
1408        assert!(matches!(
1409            result.unwrap_err(),
1410            gitflow_core::CoreError::Serialization(_)
1411        ));
1412    }
1413
1414    #[tokio::test]
1415    async fn test_should_return_platform_error_when_gc_fails_for_close() {
1416        let runner = MockCommandRunner::failure("not found", 256);
1417        let provider = GitCodePrProvider::with_runner("owner/repo", runner);
1418
1419        let result = provider.close(42).await;
1420
1421        assert!(matches!(
1422            result.unwrap_err(),
1423            gitflow_core::CoreError::Cli(_)
1424        ));
1425    }
1426
1427    #[tokio::test]
1428    async fn test_should_return_platform_error_when_gc_fails_for_reopen() {
1429        let runner = MockCommandRunner::failure("not found", 256);
1430        let provider = GitCodePrProvider::with_runner("owner/repo", runner);
1431
1432        let result = provider.reopen(42).await;
1433
1434        assert!(matches!(
1435            result.unwrap_err(),
1436            gitflow_core::CoreError::Cli(_)
1437        ));
1438    }
1439
1440    #[tokio::test]
1441    async fn test_should_return_platform_error_when_gc_fails_for_merge() {
1442        let runner = MockCommandRunner::failure("merge conflict", 256);
1443        let provider = GitCodePrProvider::with_runner("owner/repo", runner);
1444
1445        let result = provider.merge(42, None, false).await;
1446
1447        assert!(matches!(
1448            result.unwrap_err(),
1449            gitflow_core::CoreError::Cli(_)
1450        ));
1451    }
1452
1453    #[tokio::test]
1454    async fn test_should_return_platform_error_when_gc_fails_for_comment() {
1455        let runner = MockCommandRunner::failure("not found", 256);
1456        let provider = GitCodePrProvider::with_runner("owner/repo", runner);
1457
1458        let result = provider.comment(42, "a comment").await;
1459
1460        assert!(matches!(
1461            result.unwrap_err(),
1462            gitflow_core::CoreError::Cli(_)
1463        ));
1464    }
1465
1466    #[tokio::test]
1467    async fn test_should_return_platform_error_when_gc_fails_for_checkout() {
1468        let runner = MockCommandRunner::failure("git error", 256);
1469        let provider = GitCodePrProvider::with_runner("owner/repo", runner);
1470
1471        let result = provider.checkout(42).await;
1472
1473        assert!(matches!(
1474            result.unwrap_err(),
1475            gitflow_core::CoreError::Cli(_)
1476        ));
1477    }
1478
1479    #[tokio::test]
1480    async fn test_should_return_platform_error_when_gc_fails_for_sync_branch() {
1481        let runner = MockCommandRunner::failure("sync conflict", 256);
1482        let provider = GitCodePrProvider::with_runner("owner/repo", runner);
1483
1484        let result = provider.sync_branch(42).await;
1485
1486        assert!(matches!(
1487            result.unwrap_err(),
1488            gitflow_core::CoreError::Cli(_)
1489        ));
1490    }
1491
1492    #[tokio::test]
1493    async fn test_should_return_platform_error_when_gc_fails_for_mark_ready() {
1494        let runner = MockCommandRunner::failure("not a draft", 256);
1495        let provider = GitCodePrProvider::with_runner("owner/repo", runner);
1496
1497        let result = provider.mark_ready(42).await;
1498
1499        assert!(matches!(
1500            result.unwrap_err(),
1501            gitflow_core::CoreError::Cli(_)
1502        ));
1503    }
1504
1505    #[tokio::test]
1506    async fn test_should_return_platform_error_when_gc_fails_for_mark_wip() {
1507        let runner = MockCommandRunner::failure("already a draft", 256);
1508        let provider = GitCodePrProvider::with_runner("owner/repo", runner);
1509
1510        let result = provider.mark_wip(42).await;
1511
1512        assert!(matches!(
1513            result.unwrap_err(),
1514            gitflow_core::CoreError::Cli(_)
1515        ));
1516    }
1517
1518    // --- diff() tests ---
1519
1520    #[tokio::test]
1521    async fn test_should_fetch_mr_diff() {
1522        use gitflow_core::pr::PrProvider;
1523
1524        let diff_output = "diff --git a/src/main.rs b/src/main.rs\nindex 1234567..abcdefg \
1525                           100644\n--- a/src/main.rs\n+++ b/src/main.rs\n@@ -1 +1 @@\n-old\n+new\n";
1526        let runner = MockCommandRunner::success(diff_output);
1527        let provider = GitCodePrProvider::with_runner("owner/repo", runner);
1528
1529        let result = provider.diff(42).await.expect("diff should succeed");
1530        assert_eq!(result, diff_output);
1531    }
1532
1533    #[tokio::test]
1534    async fn test_should_return_error_when_mr_diff_fails() {
1535        use gitflow_core::pr::PrProvider;
1536
1537        let runner = MockCommandRunner::failure("404 not found", 256);
1538        let provider = GitCodePrProvider::with_runner("owner/repo", runner);
1539
1540        let result = provider.diff(999).await;
1541        assert!(matches!(
1542            result.unwrap_err(),
1543            gitflow_core::CoreError::Cli(_)
1544        ));
1545    }
1546
1547    // --- patch() tests ---
1548
1549    #[tokio::test]
1550    async fn test_should_fetch_mr_patch() {
1551        use gitflow_core::pr::PrProvider;
1552
1553        let patch_output =
1554            "From abc123\nSubject: [PATCH] Update file\n\ndiff --git a/src/main.rs b/src/main.rs\n";
1555        let runner = MockCommandRunner::success(patch_output);
1556        let provider = GitCodePrProvider::with_runner("owner/repo", runner);
1557
1558        let result = provider.patch(42).await.expect("patch should succeed");
1559        assert_eq!(result, patch_output);
1560    }
1561
1562    #[tokio::test]
1563    async fn test_should_return_error_when_mr_patch_fails() {
1564        use gitflow_core::pr::PrProvider;
1565
1566        let runner = MockCommandRunner::failure("404 not found", 256);
1567        let provider = GitCodePrProvider::with_runner("owner/repo", runner);
1568
1569        let result = provider.patch(999).await;
1570        assert!(matches!(
1571            result.unwrap_err(),
1572            gitflow_core::CoreError::Cli(_)
1573        ));
1574    }
1575
1576    // --- Call-shape regression tests (Issue #90) ---
1577
1578    use crate::runner::RecordingMockRunner;
1579
1580    #[tokio::test]
1581    async fn test_should_not_pass_field_list_to_pr_view() {
1582        let runner = RecordingMockRunner::success(real_gitcode_pr_json());
1583        let provider = GitCodePrProvider::with_runner("octocat/hello-world", runner.clone());
1584
1585        let pr = provider
1586            .view(20)
1587            .await
1588            .expect("view should parse real schema");
1589
1590        assert_eq!(pr.number, 52);
1591        let calls = runner.calls();
1592        assert_eq!(calls.len(), 1);
1593        assert_eq!(
1594            calls[0],
1595            vec![
1596                "pr",
1597                "view",
1598                "20",
1599                "--repo",
1600                "octocat/hello-world",
1601                "--json"
1602            ],
1603            "gitcode --json 是布尔标志,不得携带字段列表位置参数"
1604        );
1605    }
1606
1607    #[tokio::test]
1608    async fn test_should_pass_yes_flag_to_pr_close() {
1609        let runner = RecordingMockRunner::success(real_gitcode_pr_json());
1610        let provider = GitCodePrProvider::with_runner("o/r", runner.clone());
1611
1612        provider.close(9).await.expect("close should succeed");
1613
1614        let args = &runner.calls()[0];
1615        assert!(
1616            args.contains(&"--yes".to_string()),
1617            "close 必须跳过确认提示"
1618        );
1619        assert!(
1620            !args
1621                .windows(2)
1622                .any(|w| { w[0] == "--json" && w[1] != "--yes" && !w[1].starts_with('-') }),
1623            "--json 后不得跟随字段列表"
1624        );
1625    }
1626
1627    #[tokio::test]
1628    async fn test_should_deserialize_real_gitcode_pr_close_response_via_view() {
1629        // 实测响应(2026-09-21,对 byx-darwin/NexaTrade 的真实 PR #6):
1630        // `gitcode pr close --json` 只返回精简确认对象,没有 title 等字段。
1631        // close() 必须用这个精简形状拿到 number,再调用 view() 取回完整 PrData。
1632        let runner = SequencedMockCommandRunner::from_results(&[
1633            (
1634                true,
1635                r#"{"number":6,"state":"closed","owner":"byx-darwin","repo":"NexaTrade","url":"https://gitcode.com/byx-darwin/NexaTrade/merge_requests/6"}"#,
1636            ),
1637            (true, real_gitcode_pr_json()),
1638        ]);
1639        let provider = GitCodePrProvider::with_runner("owner/repo", runner.clone());
1640
1641        let pr = provider.close(6).await.expect("close should succeed");
1642
1643        assert_eq!(pr.number, 52); // real_gitcode_pr_json() 的 PR 号,证明走了 view() 而非直接转换精简响应
1644        let calls = runner.recorded_calls();
1645        assert_eq!(calls.len(), 2, "close 必须先 close 再 view 两次调用");
1646        assert!(calls[0].1.contains(&"close".to_string()));
1647        assert!(calls[1].1.contains(&"view".to_string()));
1648    }
1649
1650    #[tokio::test]
1651    async fn test_should_deserialize_real_gitcode_pr_reopen_response_via_view() {
1652        // 实测响应(2026-09-21,对 byx-darwin/NexaTrade 的真实 PR #6):
1653        // `gitcode pr reopen --json` 与 close 同形,只是 state 变为 "opened"。
1654        let runner = SequencedMockCommandRunner::from_results(&[
1655            (
1656                true,
1657                r#"{"number":6,"state":"opened","owner":"byx-darwin","repo":"NexaTrade","url":"https://gitcode.com/byx-darwin/NexaTrade/merge_requests/6"}"#,
1658            ),
1659            (true, real_gitcode_pr_json()),
1660        ]);
1661        let provider = GitCodePrProvider::with_runner("owner/repo", runner.clone());
1662
1663        let pr = provider.reopen(6).await.expect("reopen should succeed");
1664
1665        assert_eq!(pr.number, 52);
1666        let calls = runner.recorded_calls();
1667        assert_eq!(calls.len(), 2, "reopen 必须先 reopen 再 view 两次调用");
1668        assert!(calls[0].1.contains(&"reopen".to_string()));
1669        assert!(calls[1].1.contains(&"view".to_string()));
1670    }
1671
1672    #[tokio::test]
1673    async fn test_should_propagate_view_error_after_close_succeeds() {
1674        // close 命令本身成功,但紧随其后的 view() 失败——错误必须原样冒泡,
1675        // 不能吞掉伪造一个"成功但数据可能有误"的 PrData。
1676        let runner = SequencedMockCommandRunner::from_results(&[
1677            (true, r#"{"number":6,"state":"closed"}"#),
1678            (false, "gitcode: pr not found"),
1679        ]);
1680        let provider = GitCodePrProvider::with_runner("owner/repo", runner.clone());
1681
1682        let err = provider
1683            .close(6)
1684            .await
1685            .expect_err("view failure must propagate");
1686
1687        assert!(matches!(err, CoreError::Cli(_)));
1688    }
1689
1690    #[tokio::test]
1691    async fn test_should_pass_user_limit_to_pr_list_via_per_page() {
1692        let runner = RecordingMockRunner::success(&format!("[{}]", real_gitcode_pr_json()));
1693        let provider = GitCodePrProvider::with_runner("o/r", runner.clone());
1694
1695        let prs = provider
1696            .list(ListPrArgs {
1697                state: Some(State::Open),
1698                limit: Some(5),
1699            })
1700            .await
1701            .expect("list should succeed");
1702
1703        assert_eq!(prs.items.len(), 1);
1704        let args = &runner.calls()[0];
1705        // N+1 探测:cap=5 时页大小为 6,以便区分"恰好 5 条"与"还有更多"。
1706        assert!(args.windows(2).any(|w| w[0] == "--per-page" && w[1] == "6"));
1707        assert!(args.windows(2).any(|w| w[0] == "--page" && w[1] == "1"));
1708        assert!(args.contains(&"--state".to_string()));
1709        assert!(args.contains(&"open".to_string()));
1710    }
1711
1712    #[tokio::test]
1713    async fn test_should_map_squash_strategy_to_method_flag() {
1714        let runner = RecordingMockRunner::success("Merged pull request !52");
1715        let provider = GitCodePrProvider::with_runner("o/r", runner.clone());
1716
1717        let result = provider
1718            .merge(52, Some(MergeStrategy::Squash), false)
1719            .await
1720            .expect("merge");
1721
1722        assert!(result.merged);
1723        let args = &runner.calls()[0];
1724        let method_pos = args
1725            .iter()
1726            .position(|a| a == "--method")
1727            .expect("--method must be passed");
1728        assert_eq!(args[method_pos + 1], "squash");
1729    }
1730
1731    #[tokio::test]
1732    async fn test_should_map_all_merge_strategies() {
1733        for (strategy, expected) in [
1734            (MergeStrategy::Merge, "merge"),
1735            (MergeStrategy::Squash, "squash"),
1736            (MergeStrategy::Rebase, "rebase"),
1737        ] {
1738            let runner = RecordingMockRunner::success("done");
1739            let provider = GitCodePrProvider::with_runner("o/r", runner.clone());
1740            provider
1741                .merge(1, Some(strategy), false)
1742                .await
1743                .expect("merge");
1744            let args = &runner.calls()[0];
1745            let pos = args.iter().position(|a| a == "--method").expect("--method");
1746            assert_eq!(args[pos + 1], expected);
1747        }
1748    }
1749
1750    #[tokio::test]
1751    async fn test_should_omit_method_flag_when_no_strategy() {
1752        let runner = RecordingMockRunner::success("done");
1753        let provider = GitCodePrProvider::with_runner("o/r", runner.clone());
1754
1755        provider.merge(1, None, false).await.expect("merge");
1756
1757        assert!(!runner.calls()[0].contains(&"--method".to_string()));
1758    }
1759
1760    #[tokio::test]
1761    async fn test_should_reject_auto_merge_without_spawning_cli() {
1762        let runner = RecordingMockRunner::success("done");
1763        let provider = GitCodePrProvider::with_runner("o/r", runner.clone());
1764
1765        let err = provider
1766            .merge(1, None, true)
1767            .await
1768            .expect_err("GitCode has no queued-merge semantics, so auto must error");
1769
1770        assert!(
1771            matches!(err, gitflow_core::CoreError::Platform(_)),
1772            "expected CoreError::Platform, got {err:?}"
1773        );
1774        assert!(
1775            runner.calls().is_empty(),
1776            "must reject before spawning the CLI, not silently degrade to an immediate merge"
1777        );
1778    }
1779
1780    #[tokio::test]
1781    async fn test_should_not_pass_field_list_to_pr_comment() {
1782        let comment_json = r#"{"id": "9001", "body": "LGTM", "user": {"login": "rev", "id": "u9"}, "created_at": "2026-07-30T12:00:00+08:00"}"#;
1783        let runner = RecordingMockRunner::success(comment_json);
1784        let provider = GitCodePrProvider::with_runner("o/r", runner.clone());
1785
1786        let comment = provider
1787            .comment(52, "LGTM")
1788            .await
1789            .expect("comment should parse");
1790
1791        assert_eq!(comment.id, 9001);
1792        assert_eq!(comment.author.login, "rev");
1793        assert_eq!(
1794            runner.calls()[0],
1795            vec![
1796                "pr", "comment", "52", "--repo", "o/r", "--body", "LGTM", "--json"
1797            ]
1798        );
1799    }
1800
1801    #[test]
1802    fn test_should_parse_comment_with_legacy_string_author() {
1803        let json = r#"{"id": "7", "body": "old format", "author": "alice", "created_at": "2026-07-07 10:40:20"}"#;
1804        let api: PrCommentApiResponse = serde_json::from_str(json).expect("legacy shape");
1805        let comment: CommentData = api.into();
1806        assert_eq!(comment.author.login, "alice");
1807        assert_eq!(
1808            comment.created_at.map(|dt| dt.to_rfc3339()),
1809            Some("2026-07-07T10:40:20+00:00".to_string())
1810        );
1811    }
1812
1813    // --- default_branch() tests ---
1814
1815    #[tokio::test]
1816    async fn test_should_error_without_cli_call_for_default_branch() {
1817        use crate::runner::RecordingMockRunner;
1818
1819        let runner = RecordingMockRunner::success("should not be called");
1820        let provider = GitCodePrProvider::with_runner("group/project", runner.clone());
1821
1822        let result = provider.default_branch().await;
1823
1824        assert!(result.is_err());
1825        assert!(runner.calls().is_empty());
1826    }
1827}
1828
1829#[cfg(test)]
1830mod contract_tests {
1831    //! gitcode CLI v0.6.1 JSON 架构契约测试。
1832    //!
1833    //! 夹具来源:2026-07-31 对 gitcode CLI v0.6.1
1834    //!(commit c20f71f67ead1d748e78391cd9e470c2ea51b887, built 2026-06-05)
1835    //! `pr list -R byx-darwin/go-beniofit --json --state all` 的真实捕获。
1836    //! 若 gitcode CLI 升级导致这些测试失败,说明上游架构变更,需要更新
1837    //! 适配器映射并重新捕获夹具(参见路线图"契约测试 + 兼容性矩阵"单元)。
1838
1839    use gitflow_core::pr::ListPrArgs;
1840
1841    use super::*;
1842    use crate::runner::MockCommandRunner;
1843
1844    const PR_LIST_FIXTURE: &str = include_str!("../tests/fixtures/pr_list_gitcode_v0.6.json");
1845
1846    #[tokio::test]
1847    async fn test_should_parse_real_gitcode_v061_pr_list_output() {
1848        let provider = GitCodePrProvider::with_runner(
1849            "byx-darwin/go-beniofit",
1850            MockCommandRunner::success(PR_LIST_FIXTURE),
1851        );
1852
1853        let prs = provider
1854            .list(ListPrArgs::default())
1855            .await
1856            .expect("contract fixture must parse");
1857        let prs = prs.items;
1858
1859        assert_eq!(prs.len(), 1);
1860        let pr = &prs[0];
1861        assert_eq!(pr.number, 52);
1862        assert_eq!(pr.state, State::Closed);
1863        assert_eq!(pr.author.login, "byx-darwin");
1864        assert_eq!(pr.head_branch, "test/88-engine-rule-coverage");
1865        assert_eq!(pr.base_branch, "master");
1866        assert!(pr.url.starts_with("https://gitcode.com/"));
1867    }
1868}