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, Result,
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    #[serde(default)]
50    html_url: Option<String>,
51}
52
53/// gitcode PR JSON 中 `user` 对象的最小字段集。
54#[derive(Debug, Clone, Deserialize)]
55struct PrUserApi {
56    #[serde(default)]
57    login: String,
58    #[serde(default)]
59    id: Option<String>,
60}
61
62/// gitcode PR JSON 中 `head`/`base` 对象的最小字段集。
63#[derive(Debug, Clone, Deserialize)]
64struct PrBranchApi {
65    #[serde(default, rename = "ref")]
66    branch_ref: String,
67}
68
69/// gitcode CLI 评论响应类型,兼容两种已观测形态:
70/// - v0.6.x:`user` 为对象、`created_at` 为带偏移 RFC3339
71/// - 旧版本:`author` 为纯字符串、`created_at` 为 `YYYY-MM-DD HH:MM:SS`
72#[derive(Debug, Clone, Deserialize)]
73struct PrCommentApiResponse {
74    #[serde(deserialize_with = "gitflow_core::types::deserialize_u64_or_string")]
75    id: u64,
76    #[serde(default)]
77    body: String,
78    #[serde(default)]
79    author: Option<String>,
80    #[serde(default)]
81    user: Option<PrUserApi>,
82    #[serde(default)]
83    created_at: Option<String>,
84}
85
86impl From<PrCommentApiResponse> for CommentData {
87    fn from(api: PrCommentApiResponse) -> Self {
88        let author = api.user.map_or_else(
89            || UserSummary {
90                login: api.author.unwrap_or_else(|| "unknown".into()),
91                id: String::new(),
92            },
93            |u| UserSummary {
94                login: u.login,
95                id: u.id.unwrap_or_default(),
96            },
97        );
98        let created_at = api.created_at.as_deref().map_or_else(Utc::now, |s| {
99            DateTime::parse_from_rfc3339(s)
100                .map(|dt| dt.with_timezone(&Utc))
101                .or_else(|_| {
102                    chrono::NaiveDateTime::parse_from_str(s, "%Y-%m-%d %H:%M:%S")
103                        .map(|ndt| ndt.and_utc())
104                })
105                .unwrap_or_else(|_| Utc::now())
106        });
107        Self {
108            id: api.id,
109            body: api.body,
110            author,
111            created_at,
112        }
113    }
114}
115
116impl From<PrApiResponse> for PrData {
117    fn from(api: PrApiResponse) -> Self {
118        let parse_time = |s: Option<String>| {
119            s.and_then(|v| DateTime::parse_from_rfc3339(&v).ok())
120                .map_or_else(Utc::now, |dt| dt.with_timezone(&Utc))
121        };
122        Self {
123            number: api.number,
124            title: api.title,
125            body: api.body,
126            state: match api.state.as_deref() {
127                Some("closed" | "merged") => State::Closed,
128                _ => State::Open,
129            },
130            draft: api.draft,
131            author: api.user.map_or(
132                UserSummary {
133                    login: "unknown".into(),
134                    id: String::new(),
135                },
136                |u| UserSummary {
137                    login: u.login,
138                    id: u.id.unwrap_or_default(),
139                },
140            ),
141            base_branch: api.base.map_or_else(String::new, |b| b.branch_ref),
142            head_branch: api.head.map_or_else(String::new, |h| h.branch_ref),
143            created_at: parse_time(api.created_at),
144            updated_at: parse_time(api.updated_at),
145            url: api.html_url.unwrap_or_default(),
146        }
147    }
148}
149
150/// GitCode Pull Request 提供者,通过 `gitcode` CLI 操作。
151///
152/// 该结构体通过调用 `gitcode` CLI 实现 [`PrProvider`] trait 的所有方法,
153/// 使上层命令能够以统一的方式操作 GitCode Pull Request。
154///
155/// 命令执行通过 [`CommandRunner`] 抽象,生产环境默认使用
156/// [`RealCommandRunner`],测试可注入自定义 runner 以模拟成功或失败场景。
157///
158/// # Examples
159///
160/// ```no_run
161/// use gitflow_gitcode::GitCodePrProvider;
162///
163/// let provider = GitCodePrProvider::new("octocat/hello-world");
164/// ```
165#[derive(Debug, Clone)]
166pub struct GitCodePrProvider<R: CommandRunner = RealCommandRunner> {
167    /// GitCode `owner/repo`,如 `"byx-darwin/gitflow-cli"`。
168    repo: String,
169    /// 用于执行 `gitcode` CLI 命令的 runner。
170    runner: R,
171}
172
173impl GitCodePrProvider<RealCommandRunner> {
174    /// 创建新的 GitCode Pull Request 提供者。
175    ///
176    /// `repo` 格式为 `owner/repo`。
177    #[must_use]
178    pub fn new(repo: impl Into<String>) -> Self {
179        Self {
180            repo: repo.into(),
181            runner: RealCommandRunner,
182        }
183    }
184}
185
186impl<R: CommandRunner> GitCodePrProvider<R> {
187    /// 使用自定义 [`CommandRunner`] 创建提供者。
188    ///
189    /// 主要用于测试,可注入模拟 runner 以控制 `gitcode` CLI 的输出。
190    /// `repo` 格式为 `owner/repo`。
191    #[must_use]
192    pub fn with_runner(repo: impl Into<String>, runner: R) -> Self {
193        Self {
194            repo: repo.into(),
195            runner,
196        }
197    }
198}
199
200#[async_trait]
201impl<R: CommandRunner + 'static> PrProvider for GitCodePrProvider<R> {
202    async fn create(&self, args: CreatePrArgs) -> Result<PrData> {
203        let binary = crate::gitcode_binary();
204        let mut cmd_args: Vec<&str> = vec![
205            "pr",
206            "create",
207            "--repo",
208            args.repo.as_deref().unwrap_or(&self.repo),
209            "--title",
210            &args.title,
211            "--head",
212            &args.head,
213            "--base",
214            &args.base,
215            "--json",
216        ];
217
218        if let Some(body) = &args.body {
219            cmd_args.push("--body");
220            cmd_args.push(body);
221        }
222
223        if args.draft {
224            cmd_args.push("--draft");
225        }
226
227        debug!(
228            repo = %self.repo,
229            title = %args.title,
230            head = %args.head,
231            base = %args.base,
232            "spawning `gitcode pr create`"
233        );
234
235        let output = self
236            .runner
237            .run(&binary, &cmd_args)
238            .await
239            .map_err(|e| CoreError::Platform(format!("Failed to spawn gitcode: {e}")))?;
240
241        if !output.status.success() {
242            return Err(parse_gitcode_error(&output.stderr).into());
243        }
244
245        let api: PrApiResponse =
246            serde_json::from_slice(&output.stdout).map_err(CoreError::Serialization)?;
247
248        Ok(api.into())
249    }
250
251    async fn list(&self, args: ListPrArgs) -> Result<Vec<PrData>> {
252        let binary = crate::gitcode_binary();
253        let mut cmd_args: Vec<&str> = vec!["pr", "list", "--repo", &self.repo, "--json"];
254
255        if let Some(state) = &args.state {
256            cmd_args.push("--state");
257            cmd_args.push(match state {
258                State::Open => "open",
259                State::Closed => "closed",
260            });
261        }
262
263        let limit_str = args.limit.map(|limit| limit.to_string());
264        if let Some(ref limit) = limit_str {
265            cmd_args.push("--limit");
266            cmd_args.push(limit);
267        }
268
269        debug!(repo = %self.repo, "spawning `gitcode pr list`");
270
271        let output = self
272            .runner
273            .run(&binary, &cmd_args)
274            .await
275            .map_err(|e| CoreError::Platform(format!("Failed to spawn gitcode: {e}")))?;
276
277        if !output.status.success() {
278            return Err(parse_gitcode_error(&output.stderr).into());
279        }
280
281        let apis: Vec<PrApiResponse> =
282            serde_json::from_slice(&output.stdout).map_err(CoreError::Serialization)?;
283
284        Ok(apis.into_iter().map(PrData::from).collect())
285    }
286
287    async fn view(&self, number: u64) -> Result<PrData> {
288        let binary = crate::gitcode_binary();
289        let number_str = number.to_string();
290        debug!(repo = %self.repo, number, "spawning `gitcode pr view`");
291
292        let output = self
293            .runner
294            .run(
295                &binary,
296                &["pr", "view", &number_str, "--repo", &self.repo, "--json"],
297            )
298            .await
299            .map_err(|e| CoreError::Platform(format!("Failed to spawn gitcode: {e}")))?;
300
301        if !output.status.success() {
302            return Err(parse_gitcode_error(&output.stderr).into());
303        }
304
305        let api: PrApiResponse =
306            serde_json::from_slice(&output.stdout).map_err(CoreError::Serialization)?;
307
308        Ok(api.into())
309    }
310
311    /// 关闭指定编号的 PR。
312    ///
313    /// 调用 `gitcode pr close <number> --repo <repo> --yes --json` 关闭 PR,
314    /// 并返回更新后的完整 PR 数据。
315    ///
316    /// # Errors
317    ///
318    /// 当 PR 不存在、已关闭或 `gitcode` CLI 调用失败时返回错误。
319    async fn close(&self, number: u64) -> Result<PrData> {
320        let binary = crate::gitcode_binary();
321        let number_str = number.to_string();
322        debug!(repo = %self.repo, number, "spawning `gitcode pr close`");
323
324        let output = self
325            .runner
326            .run(
327                &binary,
328                &[
329                    "pr",
330                    "close",
331                    &number_str,
332                    "--repo",
333                    &self.repo,
334                    "--yes",
335                    "--json",
336                ],
337            )
338            .await
339            .map_err(|e| CoreError::Platform(format!("Failed to spawn gitcode: {e}")))?;
340
341        if !output.status.success() {
342            return Err(parse_gitcode_error(&output.stderr).into());
343        }
344
345        let api: PrApiResponse =
346            serde_json::from_slice(&output.stdout).map_err(CoreError::Serialization)?;
347
348        Ok(api.into())
349    }
350
351    /// 重新打开指定编号的 PR。
352    ///
353    /// 调用 `gitcode pr reopen <number> --repo <repo> --yes --json` 重新打开已关闭的 PR,
354    /// 并返回更新后的完整 PR 数据。
355    ///
356    /// # Errors
357    ///
358    /// 当 PR 不存在、未关闭或 `gitcode` CLI 调用失败时返回错误。
359    async fn reopen(&self, number: u64) -> Result<PrData> {
360        let binary = crate::gitcode_binary();
361        let number_str = number.to_string();
362        debug!(repo = %self.repo, number, "spawning `gitcode pr reopen`");
363
364        let output = self
365            .runner
366            .run(
367                &binary,
368                &[
369                    "pr",
370                    "reopen",
371                    &number_str,
372                    "--repo",
373                    &self.repo,
374                    "--yes",
375                    "--json",
376                ],
377            )
378            .await
379            .map_err(|e| CoreError::Platform(format!("Failed to spawn gitcode: {e}")))?;
380
381        if !output.status.success() {
382            return Err(parse_gitcode_error(&output.stderr).into());
383        }
384
385        let api: PrApiResponse =
386            serde_json::from_slice(&output.stdout).map_err(CoreError::Serialization)?;
387
388        Ok(api.into())
389    }
390
391    /// 在指定 PR 上添加评论。
392    ///
393    /// 调用 `gitcode pr comment <number> --repo <repo> --body "<body>" --json`
394    /// 发布评论,并返回新建评论的数据。
395    ///
396    /// # Errors
397    ///
398    /// 当 PR 不存在、`body` 为空或 `gitcode` CLI 调用失败时返回错误。
399    async fn comment(&self, number: u64, body: &str) -> Result<CommentData> {
400        let binary = crate::gitcode_binary();
401        let number_str = number.to_string();
402        debug!(repo = %self.repo, number, "spawning `gitcode pr comment`");
403
404        let output = self
405            .runner
406            .run(
407                &binary,
408                &[
409                    "pr",
410                    "comment",
411                    &number_str,
412                    "--repo",
413                    &self.repo,
414                    "--body",
415                    body,
416                    "--json",
417                ],
418            )
419            .await
420            .map_err(|e| CoreError::Platform(format!("Failed to spawn gitcode: {e}")))?;
421
422        if !output.status.success() {
423            return Err(parse_gitcode_error(&output.stderr).into());
424        }
425
426        let api: PrCommentApiResponse =
427            serde_json::from_slice(&output.stdout).map_err(CoreError::Serialization)?;
428
429        Ok(api.into())
430    }
431
432    /// 合并指定编号的 PR。
433    ///
434    /// 调用 `gitcode pr merge <number> --repo <repo> --yes [--method <strategy>]`
435    /// 合并 PR。`strategy` 映射到 gitcode 的 `--method` 参数
436    ///(`merge` / `squash` / `rebase`);未指定时使用平台默认策略。
437    ///
438    /// # Errors
439    ///
440    /// 当 PR 不存在、存在冲突无法合并或 `gitcode` CLI 调用失败时返回错误。
441    async fn merge(&self, number: u64, strategy: Option<MergeStrategy>) -> Result<MergeResult> {
442        let binary = crate::gitcode_binary();
443        let number_str = number.to_string();
444        let mut cmd_args: Vec<&str> =
445            vec!["pr", "merge", &number_str, "--repo", &self.repo, "--yes"];
446
447        let strategy_value;
448        if let Some(strategy) = strategy {
449            strategy_value = match strategy {
450                MergeStrategy::Merge => "merge",
451                MergeStrategy::Squash => "squash",
452                MergeStrategy::Rebase => "rebase",
453            };
454            cmd_args.push("--method");
455            cmd_args.push(strategy_value);
456        }
457
458        debug!(repo = %self.repo, number, ?strategy, "spawning `gitcode pr merge`");
459
460        let output = self
461            .runner
462            .run(&binary, &cmd_args)
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        // `gitcode pr merge` outputs a human-readable message, not JSON.
471        let message = String::from_utf8_lossy(&output.stdout).trim().to_string();
472        Ok(MergeResult {
473            merged: true,
474            sha: None,
475            message: Some(message),
476        })
477    }
478
479    /// 在本地检出指定 PR 的分支。
480    ///
481    /// 调用 `gc pr checkout <number> --repo <repo>` 在本地工作区创建并切换到
482    /// PR 的来源分支。如果本地已存在该分支,则尝试更新它。
483    ///
484    /// # Errors
485    ///
486    /// 当 PR 不存在、本地 git 操作失败或 `gitcode` CLI 调用失败时返回错误。
487    async fn checkout(&self, number: u64) -> Result<()> {
488        let binary = crate::gitcode_binary();
489        let number_str = number.to_string();
490        debug!(repo = %self.repo, number, "spawning `gc pr checkout`");
491
492        let output = self
493            .runner
494            .run(
495                &binary,
496                &["pr", "checkout", &number_str, "--repo", &self.repo],
497            )
498            .await
499            .map_err(|e| CoreError::Platform(format!("Failed to spawn gitcode: {e}")))?;
500
501        if !output.status.success() {
502            return Err(parse_gitcode_error(&output.stderr).into());
503        }
504
505        Ok(())
506    }
507
508    /// 将草稿 PR 标记为可审查状态(ready for review)。
509    ///
510    /// 调用 `gc pr ready <number> --repo <repo>` 将草稿 PR 转为可审查状态,
511    /// 并通过 `gc pr view` 重新获取更新后的 PR 数据。
512    ///
513    /// # Errors
514    ///
515    /// 当 PR 不存在、不是草稿状态或 `gitcode` CLI 调用失败时返回错误。
516    async fn mark_ready(&self, number: u64) -> Result<PrData> {
517        let binary = crate::gitcode_binary();
518        let number_str = number.to_string();
519        debug!(repo = %self.repo, number, "spawning `gc pr ready`");
520
521        let output = self
522            .runner
523            .run(&binary, &["pr", "ready", &number_str, "--repo", &self.repo])
524            .await
525            .map_err(|e| CoreError::Platform(format!("Failed to spawn gitcode: {e}")))?;
526
527        if !output.status.success() {
528            return Err(parse_gitcode_error(&output.stderr).into());
529        }
530
531        // `gc pr ready` does not return JSON; re-fetch the PR to get updated data.
532        self.view(number).await
533    }
534
535    /// 将 PR 标记为草稿状态(work in progress)。
536    ///
537    /// 调用 `gc pr convert-to-draft <number> --repo <repo>` 将可审查的 PR 转为草稿,
538    /// 并通过 `gc pr view` 重新获取更新后的 PR 数据。
539    ///
540    /// # Errors
541    ///
542    /// 当 PR 不存在、已是草稿状态或 `gitcode` CLI 调用失败时返回错误。
543    async fn mark_wip(&self, number: u64) -> Result<PrData> {
544        let binary = crate::gitcode_binary();
545        let number_str = number.to_string();
546        debug!(repo = %self.repo, number, "spawning `gc pr convert-to-draft`");
547
548        let output = self
549            .runner
550            .run(
551                &binary,
552                &["pr", "convert-to-draft", &number_str, "--repo", &self.repo],
553            )
554            .await
555            .map_err(|e| CoreError::Platform(format!("Failed to spawn gitcode: {e}")))?;
556
557        if !output.status.success() {
558            return Err(parse_gitcode_error(&output.stderr).into());
559        }
560
561        // `gc pr convert-to-draft` does not return JSON; re-fetch the PR.
562        self.view(number).await
563    }
564
565    /// 同步 PR 的分支(将 base 分支的最新变更合入 head 分支)。
566    ///
567    /// 调用 `gc pr update-branch <number> --repo <repo>` 将 PR 的来源分支
568    /// 更新到与目标分支的最新状态同步,解决分支过时问题。
569    ///
570    /// # Errors
571    ///
572    /// 当 PR 不存在、同步存在冲突或 `gitcode` CLI 调用失败时返回错误。
573    async fn sync_branch(&self, number: u64) -> Result<()> {
574        let binary = crate::gitcode_binary();
575        let number_str = number.to_string();
576        debug!(repo = %self.repo, number, "spawning `gc pr update-branch`");
577
578        let output = self
579            .runner
580            .run(
581                &binary,
582                &["pr", "update-branch", &number_str, "--repo", &self.repo],
583            )
584            .await
585            .map_err(|e| CoreError::Platform(format!("Failed to spawn gitcode: {e}")))?;
586
587        if !output.status.success() {
588            return Err(parse_gitcode_error(&output.stderr).into());
589        }
590
591        Ok(())
592    }
593}
594
595#[cfg(test)]
596mod tests {
597    use super::*;
598    use crate::runner::MockCommandRunner;
599
600    /// gitcode CLI v0.6.1 `pr list/view --json` 的真实输出结构(2026-07-31 实测捕获,已精简)。
601    fn real_gitcode_pr_json() -> &'static str {
602        r###"{
603            "id": 8957463,
604            "number": 52,
605            "title": "test(badge): 引擎规则函数测试覆盖",
606            "body": "## Summary\n\nCloses #88",
607            "description": "## Summary\n\nCloses #88",
608            "state": "merged",
609            "html_url": "https://gitcode.com/byx-darwin/go-beniofit/merge_requests/52",
610            "diff_url": "",
611            "patch_url": "",
612            "draft": false,
613            "merged": true,
614            "merged_at": "2026-07-30T13:23:13+08:00",
615            "created_at": "2026-07-30T12:40:46+08:00",
616            "updated_at": "2026-07-30T13:23:13+08:00",
617            "user": {
618                "id": "66767cd4096c81780c61bf07",
619                "login": "byx-darwin",
620                "name": "baoyx",
621                "email": "",
622                "avatar_url": "https://cdn-img.gitcode.com/avatar.png",
623                "html_url": "https://gitcode.com/byx-darwin",
624                "created_at": ""
625            },
626            "head": {
627                "label": "test/88-engine-rule-coverage",
628                "ref": "test/88-engine-rule-coverage",
629                "sha": "8f1d3f31d7ee598a16f40fcac55b86154122c93c"
630            },
631            "base": {
632                "label": "master",
633                "ref": "master",
634                "sha": "bba7d724c8c73531acf1dca5f639b2a273c26eae"
635            },
636            "labels": [],
637            "assignees": [],
638            "additions": 120,
639            "deletions": 3,
640            "changed_files": 1,
641            "commits": 2,
642            "comments": 0,
643            "mergeable": true,
644            "mergeable_state": "can_be_merged",
645            "milestone": null,
646            "closed_at": "2026-07-30T13:23:13+08:00",
647            "requested_reviewers": []
648        }"###
649    }
650
651    #[test]
652    fn test_should_map_real_gitcode_pr_response_to_pr_data() {
653        let api: PrApiResponse =
654            serde_json::from_str(real_gitcode_pr_json()).expect(r"valid gitcode v0.6.1 PR JSON");
655        let pr: PrData = api.into();
656
657        assert_eq!(pr.number, 52);
658        assert_eq!(pr.title, r"test(badge): 引擎规则函数测试覆盖");
659        assert_eq!(pr.state, State::Closed, r"merged 必须映射为 Closed");
660        assert!(!pr.draft);
661        assert_eq!(pr.author.login, "byx-darwin");
662        assert_eq!(pr.author.id, "66767cd4096c81780c61bf07");
663        assert_eq!(pr.base_branch, "master");
664        assert_eq!(pr.head_branch, "test/88-engine-rule-coverage");
665        assert_eq!(
666            pr.url,
667            "https://gitcode.com/byx-darwin/go-beniofit/merge_requests/52"
668        );
669        assert_eq!(pr.created_at.to_rfc3339(), "2026-07-30T04:40:46+00:00");
670    }
671
672    #[test]
673    fn test_should_map_open_pr_with_minimal_gitcode_fields() {
674        let json = r#"{
675            "id": 1,
676            "number": 7,
677            "title": "New work",
678            "state": "open",
679            "html_url": "https://gitcode.com/o/r/merge_requests/7",
680            "draft": true,
681            "user": {"id": "u1", "login": "dev"},
682            "head": {"ref": "feature/x"},
683            "base": {"ref": "main"}
684        }"#;
685        let api: PrApiResponse = serde_json::from_str(json).expect(r"minimal gitcode PR JSON");
686        let pr: PrData = api.into();
687
688        assert_eq!(pr.state, State::Open);
689        assert!(pr.draft);
690        assert_eq!(pr.body, None);
691        assert_eq!(pr.head_branch, "feature/x");
692        assert_eq!(pr.base_branch, "main");
693        assert_eq!(pr.author.login, "dev");
694    }
695
696    #[test]
697    fn test_should_construct_gitcode_pr_provider() {
698        let provider = GitCodePrProvider::new("octocat/hello-world");
699        assert_eq!(provider.repo, "octocat/hello-world");
700    }
701
702    #[test]
703    fn test_should_construct_gitcode_pr_provider_from_string() {
704        let repo = String::from("octocat/hello-world");
705        let provider = GitCodePrProvider::new(repo);
706        assert_eq!(provider.repo, "octocat/hello-world");
707    }
708
709    #[test]
710    fn test_should_deserialize_empty_pr_list_from_gc_output() {
711        let gc_json = b"[]";
712        let prs: Vec<PrData> = serde_json::from_slice(gc_json).expect("valid PrData list");
713        assert!(prs.is_empty());
714    }
715
716    #[test]
717    fn test_should_debug_format_provider() {
718        let provider = GitCodePrProvider::new("octocat/hello-world");
719        let debug = format!("{provider:?}");
720        assert!(debug.contains("GitCodePrProvider"));
721        assert!(debug.contains("octocat/hello-world"));
722    }
723
724    #[test]
725    fn test_should_deserialize_comment_data_from_gc_pr_comment_output() {
726        let gc_json = br#"{
727            "id": 2002,
728            "body": "Approved, merging now.",
729            "author": {"login": "reviewer", "id": "88"},
730            "createdAt": "2026-06-20T16:00:00Z"
731        }"#;
732
733        let comment: CommentData = serde_json::from_slice(gc_json).expect("valid CommentData");
734        assert_eq!(comment.id, 2002);
735        assert_eq!(comment.body, "Approved, merging now.");
736        assert_eq!(comment.author.login, "reviewer");
737        assert_eq!(comment.author.id, "88");
738    }
739
740    #[test]
741    fn test_should_deserialize_merge_result_from_gc_merge_output() {
742        let gc_text = b"Pull request #123 was successfully merged.\n";
743        let message = String::from_utf8_lossy(gc_text).trim().to_string();
744        let result = MergeResult {
745            merged: true,
746            sha: None,
747            message: Some(message),
748        };
749
750        assert!(result.merged);
751        assert!(result.message.as_deref().is_some());
752        assert_eq!(
753            result.message.as_deref(),
754            Some("Pull request #123 was successfully merged.")
755        );
756    }
757
758    #[test]
759    fn test_should_roundtrip_merge_result_via_serde() {
760        let result = MergeResult {
761            merged: true,
762            sha: Some("deadbeef1234".into()),
763            message: Some("Squash merged".into()),
764        };
765        let json = serde_json::to_string(&result).expect("serialize");
766        let round_tripped: MergeResult = serde_json::from_str(&json).expect("deserialize");
767        assert!(round_tripped.merged);
768        assert_eq!(round_tripped.sha, result.sha);
769        assert_eq!(round_tripped.message, result.message);
770    }
771
772    #[test]
773    fn test_should_serialize_merge_result_skips_null_fields() {
774        let result = MergeResult {
775            merged: false,
776            sha: None,
777            message: None,
778        };
779        let json = serde_json::to_string(&result).expect("serialize");
780        assert!(!json.contains("null"));
781        assert_eq!(json, r#"{"merged":false}"#);
782    }
783
784    #[test]
785    fn test_should_create_provider_with_different_repos() {
786        let r1 = GitCodePrProvider::new("org/repo-a");
787        let r2 = GitCodePrProvider::new("org/repo-b");
788        assert_eq!(r1.repo, "org/repo-a");
789        assert_eq!(r2.repo, "org/repo-b");
790    }
791
792    #[test]
793    fn test_should_clone_gitcode_pr_provider() {
794        let original = GitCodePrProvider::new("owner/repo");
795        let cloned = original.clone();
796        assert_eq!(original.repo, cloned.repo);
797    }
798
799    // --- Failure-path tests using an injected MockCommandRunner ---
800
801    fn sample_create_args() -> CreatePrArgs {
802        CreatePrArgs {
803            title: "New feature".to_string(),
804            body: Some("Adds a feature".to_string()),
805            head: "feature/x".to_string(),
806            base: "main".to_string(),
807            draft: false,
808            repo: None,
809        }
810    }
811
812    #[tokio::test]
813    async fn test_should_return_platform_error_when_gc_fails_for_create() {
814        let runner = MockCommandRunner::failure("validation failed", 256);
815        let provider = GitCodePrProvider::with_runner("owner/repo", runner);
816
817        let result = provider.create(sample_create_args()).await;
818
819        assert!(matches!(
820            result.unwrap_err(),
821            gitflow_core::CoreError::Cli(_)
822        ));
823    }
824
825    #[tokio::test]
826    async fn test_should_return_serialization_error_on_invalid_json_for_create() {
827        let runner = MockCommandRunner::success("not valid json");
828        let provider = GitCodePrProvider::with_runner("owner/repo", runner);
829
830        let result = provider.create(sample_create_args()).await;
831
832        assert!(matches!(
833            result.unwrap_err(),
834            gitflow_core::CoreError::Serialization(_)
835        ));
836    }
837
838    #[tokio::test]
839    async fn test_should_return_platform_error_when_gc_fails_for_list() {
840        let runner = MockCommandRunner::failure("forbidden", 256);
841        let provider = GitCodePrProvider::with_runner("owner/repo", runner);
842
843        let result = provider.list(ListPrArgs::default()).await;
844
845        assert!(matches!(
846            result.unwrap_err(),
847            gitflow_core::CoreError::Cli(_)
848        ));
849    }
850
851    #[tokio::test]
852    async fn test_should_return_serialization_error_on_invalid_json_for_list() {
853        let runner = MockCommandRunner::success("invalid");
854        let provider = GitCodePrProvider::with_runner("owner/repo", runner);
855
856        let result = provider.list(ListPrArgs::default()).await;
857
858        assert!(matches!(
859            result.unwrap_err(),
860            gitflow_core::CoreError::Serialization(_)
861        ));
862    }
863
864    #[tokio::test]
865    async fn test_should_return_platform_error_when_gc_fails_for_view() {
866        let runner = MockCommandRunner::failure("pr not found", 256);
867        let provider = GitCodePrProvider::with_runner("owner/repo", runner);
868
869        let result = provider.view(999).await;
870
871        assert!(matches!(
872            result.unwrap_err(),
873            gitflow_core::CoreError::Cli(_)
874        ));
875    }
876
877    #[tokio::test]
878    async fn test_should_return_serialization_error_on_invalid_json_for_view() {
879        let runner = MockCommandRunner::success("not valid json");
880        let provider = GitCodePrProvider::with_runner("owner/repo", runner);
881
882        let result = provider.view(1).await;
883
884        assert!(matches!(
885            result.unwrap_err(),
886            gitflow_core::CoreError::Serialization(_)
887        ));
888    }
889
890    #[tokio::test]
891    async fn test_should_return_platform_error_when_gc_fails_for_close() {
892        let runner = MockCommandRunner::failure("not found", 256);
893        let provider = GitCodePrProvider::with_runner("owner/repo", runner);
894
895        let result = provider.close(42).await;
896
897        assert!(matches!(
898            result.unwrap_err(),
899            gitflow_core::CoreError::Cli(_)
900        ));
901    }
902
903    #[tokio::test]
904    async fn test_should_return_platform_error_when_gc_fails_for_reopen() {
905        let runner = MockCommandRunner::failure("not found", 256);
906        let provider = GitCodePrProvider::with_runner("owner/repo", runner);
907
908        let result = provider.reopen(42).await;
909
910        assert!(matches!(
911            result.unwrap_err(),
912            gitflow_core::CoreError::Cli(_)
913        ));
914    }
915
916    #[tokio::test]
917    async fn test_should_return_platform_error_when_gc_fails_for_merge() {
918        let runner = MockCommandRunner::failure("merge conflict", 256);
919        let provider = GitCodePrProvider::with_runner("owner/repo", runner);
920
921        let result = provider.merge(42, None).await;
922
923        assert!(matches!(
924            result.unwrap_err(),
925            gitflow_core::CoreError::Cli(_)
926        ));
927    }
928
929    #[tokio::test]
930    async fn test_should_return_platform_error_when_gc_fails_for_comment() {
931        let runner = MockCommandRunner::failure("not found", 256);
932        let provider = GitCodePrProvider::with_runner("owner/repo", runner);
933
934        let result = provider.comment(42, "a comment").await;
935
936        assert!(matches!(
937            result.unwrap_err(),
938            gitflow_core::CoreError::Cli(_)
939        ));
940    }
941
942    #[tokio::test]
943    async fn test_should_return_platform_error_when_gc_fails_for_checkout() {
944        let runner = MockCommandRunner::failure("git error", 256);
945        let provider = GitCodePrProvider::with_runner("owner/repo", runner);
946
947        let result = provider.checkout(42).await;
948
949        assert!(matches!(
950            result.unwrap_err(),
951            gitflow_core::CoreError::Cli(_)
952        ));
953    }
954
955    #[tokio::test]
956    async fn test_should_return_platform_error_when_gc_fails_for_sync_branch() {
957        let runner = MockCommandRunner::failure("sync conflict", 256);
958        let provider = GitCodePrProvider::with_runner("owner/repo", runner);
959
960        let result = provider.sync_branch(42).await;
961
962        assert!(matches!(
963            result.unwrap_err(),
964            gitflow_core::CoreError::Cli(_)
965        ));
966    }
967
968    #[tokio::test]
969    async fn test_should_return_platform_error_when_gc_fails_for_mark_ready() {
970        let runner = MockCommandRunner::failure("not a draft", 256);
971        let provider = GitCodePrProvider::with_runner("owner/repo", runner);
972
973        let result = provider.mark_ready(42).await;
974
975        assert!(matches!(
976            result.unwrap_err(),
977            gitflow_core::CoreError::Cli(_)
978        ));
979    }
980
981    #[tokio::test]
982    async fn test_should_return_platform_error_when_gc_fails_for_mark_wip() {
983        let runner = MockCommandRunner::failure("already a draft", 256);
984        let provider = GitCodePrProvider::with_runner("owner/repo", runner);
985
986        let result = provider.mark_wip(42).await;
987
988        assert!(matches!(
989            result.unwrap_err(),
990            gitflow_core::CoreError::Cli(_)
991        ));
992    }
993
994    // --- Call-shape regression tests (Issue #90) ---
995
996    use crate::runner::RecordingMockRunner;
997
998    #[tokio::test]
999    async fn test_should_not_pass_field_list_to_pr_view() {
1000        let runner = RecordingMockRunner::success(real_gitcode_pr_json());
1001        let provider = GitCodePrProvider::with_runner("octocat/hello-world", runner.clone());
1002
1003        let pr = provider
1004            .view(20)
1005            .await
1006            .expect("view should parse real schema");
1007
1008        assert_eq!(pr.number, 52);
1009        let calls = runner.calls();
1010        assert_eq!(calls.len(), 1);
1011        assert_eq!(
1012            calls[0],
1013            vec![
1014                "pr",
1015                "view",
1016                "20",
1017                "--repo",
1018                "octocat/hello-world",
1019                "--json"
1020            ],
1021            "gitcode --json 是布尔标志,不得携带字段列表位置参数"
1022        );
1023    }
1024
1025    #[tokio::test]
1026    async fn test_should_pass_yes_flag_to_pr_close() {
1027        let runner = RecordingMockRunner::success(real_gitcode_pr_json());
1028        let provider = GitCodePrProvider::with_runner("o/r", runner.clone());
1029
1030        provider.close(9).await.expect("close should succeed");
1031
1032        let args = &runner.calls()[0];
1033        assert!(
1034            args.contains(&"--yes".to_string()),
1035            "close 必须跳过确认提示"
1036        );
1037        assert!(
1038            !args
1039                .windows(2)
1040                .any(|w| { w[0] == "--json" && w[1] != "--yes" && !w[1].starts_with('-') }),
1041            "--json 后不得跟随字段列表"
1042        );
1043    }
1044
1045    #[tokio::test]
1046    async fn test_should_pass_limit_flag_to_pr_list() {
1047        let runner = RecordingMockRunner::success(&format!("[{}]", real_gitcode_pr_json()));
1048        let provider = GitCodePrProvider::with_runner("o/r", runner.clone());
1049
1050        let prs = provider
1051            .list(ListPrArgs {
1052                state: Some(State::Open),
1053                limit: Some(5),
1054            })
1055            .await
1056            .expect("list should succeed");
1057
1058        assert_eq!(prs.len(), 1);
1059        let args = &runner.calls()[0];
1060        assert!(args.contains(&"--limit".to_string()));
1061        assert!(args.contains(&"5".to_string()));
1062        assert!(args.contains(&"--state".to_string()));
1063        assert!(args.contains(&"open".to_string()));
1064    }
1065
1066    #[tokio::test]
1067    async fn test_should_map_squash_strategy_to_method_flag() {
1068        let runner = RecordingMockRunner::success("Merged pull request !52");
1069        let provider = GitCodePrProvider::with_runner("o/r", runner.clone());
1070
1071        let result = provider
1072            .merge(52, Some(MergeStrategy::Squash))
1073            .await
1074            .expect("merge");
1075
1076        assert!(result.merged);
1077        let args = &runner.calls()[0];
1078        let method_pos = args
1079            .iter()
1080            .position(|a| a == "--method")
1081            .expect("--method must be passed");
1082        assert_eq!(args[method_pos + 1], "squash");
1083    }
1084
1085    #[tokio::test]
1086    async fn test_should_map_all_merge_strategies() {
1087        for (strategy, expected) in [
1088            (MergeStrategy::Merge, "merge"),
1089            (MergeStrategy::Squash, "squash"),
1090            (MergeStrategy::Rebase, "rebase"),
1091        ] {
1092            let runner = RecordingMockRunner::success("done");
1093            let provider = GitCodePrProvider::with_runner("o/r", runner.clone());
1094            provider.merge(1, Some(strategy)).await.expect("merge");
1095            let args = &runner.calls()[0];
1096            let pos = args.iter().position(|a| a == "--method").expect("--method");
1097            assert_eq!(args[pos + 1], expected);
1098        }
1099    }
1100
1101    #[tokio::test]
1102    async fn test_should_omit_method_flag_when_no_strategy() {
1103        let runner = RecordingMockRunner::success("done");
1104        let provider = GitCodePrProvider::with_runner("o/r", runner.clone());
1105
1106        provider.merge(1, None).await.expect("merge");
1107
1108        assert!(!runner.calls()[0].contains(&"--method".to_string()));
1109    }
1110
1111    #[tokio::test]
1112    async fn test_should_not_pass_field_list_to_pr_comment() {
1113        let comment_json = r#"{"id": "9001", "body": "LGTM", "user": {"login": "rev", "id": "u9"}, "created_at": "2026-07-30T12:00:00+08:00"}"#;
1114        let runner = RecordingMockRunner::success(comment_json);
1115        let provider = GitCodePrProvider::with_runner("o/r", runner.clone());
1116
1117        let comment = provider
1118            .comment(52, "LGTM")
1119            .await
1120            .expect("comment should parse");
1121
1122        assert_eq!(comment.id, 9001);
1123        assert_eq!(comment.author.login, "rev");
1124        assert_eq!(
1125            runner.calls()[0],
1126            vec![
1127                "pr", "comment", "52", "--repo", "o/r", "--body", "LGTM", "--json"
1128            ]
1129        );
1130    }
1131
1132    #[test]
1133    fn test_should_parse_comment_with_legacy_string_author() {
1134        let json = r#"{"id": "7", "body": "old format", "author": "alice", "created_at": "2026-07-07 10:40:20"}"#;
1135        let api: PrCommentApiResponse = serde_json::from_str(json).expect("legacy shape");
1136        let comment: CommentData = api.into();
1137        assert_eq!(comment.author.login, "alice");
1138        assert_eq!(comment.created_at.to_rfc3339(), "2026-07-07T10:40:20+00:00");
1139    }
1140}
1141
1142#[cfg(test)]
1143mod contract_tests {
1144    //! gitcode CLI v0.6.1 JSON 架构契约测试。
1145    //!
1146    //! 夹具来源:2026-07-31 对 gitcode CLI v0.6.1
1147    //!(commit c20f71f67ead1d748e78391cd9e470c2ea51b887, built 2026-06-05)
1148    //! `pr list -R byx-darwin/go-beniofit --json --state all` 的真实捕获。
1149    //! 若 gitcode CLI 升级导致这些测试失败,说明上游架构变更,需要更新
1150    //! 适配器映射并重新捕获夹具(参见路线图"契约测试 + 兼容性矩阵"单元)。
1151
1152    use gitflow_core::pr::ListPrArgs;
1153
1154    use super::*;
1155    use crate::runner::MockCommandRunner;
1156
1157    const PR_LIST_FIXTURE: &str = include_str!("../tests/fixtures/pr_list_gitcode_v0.6.json");
1158
1159    #[tokio::test]
1160    async fn test_should_parse_real_gitcode_v061_pr_list_output() {
1161        let provider = GitCodePrProvider::with_runner(
1162            "byx-darwin/go-beniofit",
1163            MockCommandRunner::success(PR_LIST_FIXTURE),
1164        );
1165
1166        let prs = provider
1167            .list(ListPrArgs::default())
1168            .await
1169            .expect("contract fixture must parse");
1170
1171        assert_eq!(prs.len(), 1);
1172        let pr = &prs[0];
1173        assert_eq!(pr.number, 52);
1174        assert_eq!(pr.state, State::Closed);
1175        assert_eq!(pr.author.login, "byx-darwin");
1176        assert_eq!(pr.head_branch, "test/88-engine-rule-coverage");
1177        assert_eq!(pr.base_branch, "master");
1178        assert!(pr.url.starts_with("https://gitcode.com/"));
1179    }
1180}