Skip to main content

gitflow_gitcode/
issue.rs

1//! GitCode Issue 提供者实现。
2//!
3//! 通过 `gitcode` CLI 实现 [`IssueProvider`] trait。GitCode CLI
4//! 使用 `-R` 指定仓库、`--json` 为布尔标志、`version` 子命令检测版本。
5//! JSON 响应字段名与 GitHub/GitLab CLI 不同(`user` 而非 `author` 等),
6//! 通过 [`IssueApiResponse`] 做字段映射后转换为 core 类型。
7
8use async_trait::async_trait;
9use chrono::{DateTime, Utc};
10use gitflow_core::{
11    CoreError, DEFAULT_LIST_LIMIT, FetchStrategy, Paged, Result, Session, fetch_capped,
12    issue::{CreateIssueArgs, EditIssueArgs, IssueData, IssueProvider, ListIssueArgs},
13    types::{CommentData, Label, State, UserSummary},
14};
15use serde::Deserialize;
16use tracing::debug;
17
18use crate::{
19    error::parse_gitcode_error,
20    runner::{CommandRunner, RealCommandRunner},
21};
22
23/// gitcode CLI `issue list --json` 的响应类型。
24#[derive(Debug, Clone, Deserialize)]
25#[serde(rename_all = "lowercase")]
26struct IssueApiResponse {
27    number: String,
28    title: String,
29    body: Option<String>,
30    state: String,
31    #[serde(default)]
32    labels: Option<Vec<LabelApi>>,
33    user: Option<UserApi>,
34    #[serde(default)]
35    assignees: Option<Vec<UserApi>>,
36    created_at: Option<String>,
37    updated_at: Option<String>,
38    html_url: String,
39    #[serde(default)]
40    milestone: Option<MilestoneRefApi>,
41}
42
43/// gitcode CLI 嵌入在 issue/PR 响应中的 `milestone` 对象的最小字段集。
44///
45/// 真实形状(2026-09-21 对 `byx-darwin/NexaTrade` issue #1 的实测捕获,
46/// `gitcode issue view --json`):
47/// ```json
48/// {"id": null, "number": 866493, "title": "gf-357-test-milestone",
49///  "description": "", "state": "active", "due_on": "2026-10-21"}
50/// ```
51/// 只映射 `number`/`title`:与 `gitflow_core::types::MilestoneRef` 的契约一致,
52/// `id`/`description`/`state`/`due_on` 由 `gf milestone view` 单独提供。
53#[derive(Debug, Clone, Deserialize)]
54struct MilestoneRefApi {
55    number: u64,
56    title: String,
57}
58
59impl From<MilestoneRefApi> for gitflow_core::types::MilestoneRef {
60    fn from(api: MilestoneRefApi) -> Self {
61        Self {
62            number: api.number,
63            title: api.title,
64        }
65    }
66}
67
68#[derive(Debug, Clone, Deserialize)]
69#[serde(rename_all = "lowercase")]
70struct LabelApi {
71    name: String,
72    #[serde(default)]
73    color: Option<String>,
74    #[serde(default)]
75    description: Option<String>,
76}
77
78#[derive(Debug, Clone, Deserialize)]
79struct UserApi {
80    login: String,
81    #[serde(default)]
82    id: Option<String>,
83}
84
85impl From<IssueApiResponse> for IssueData {
86    fn from(api: IssueApiResponse) -> Self {
87        Self {
88            number: api.number.parse().unwrap_or(0),
89            title: api.title,
90            body: api.body,
91            state: match api.state.as_str() {
92                "closed" => State::Closed,
93                _ => State::Open,
94            },
95            labels: api
96                .labels
97                .unwrap_or_default()
98                .into_iter()
99                .map(Label::from)
100                .collect(),
101            author: api.user.map_or(
102                UserSummary {
103                    login: "unknown".into(),
104                    id: String::new(),
105                },
106                UserSummary::from,
107            ),
108            assignees: api
109                .assignees
110                .unwrap_or_default()
111                .into_iter()
112                .map(UserSummary::from)
113                .collect(),
114            created_at: api.created_at.and_then(|s| {
115                DateTime::parse_from_rfc3339(&s)
116                    .ok()
117                    .map(|d| d.with_timezone(&Utc))
118            }),
119            updated_at: api.updated_at.and_then(|s| {
120                DateTime::parse_from_rfc3339(&s)
121                    .ok()
122                    .map(|d| d.with_timezone(&Utc))
123            }),
124            url: api.html_url,
125            milestone: api.milestone.map(Into::into),
126        }
127    }
128}
129
130impl From<LabelApi> for Label {
131    fn from(api: LabelApi) -> Self {
132        Self {
133            name: api.name,
134            color: api.color,
135            description: api.description,
136        }
137    }
138}
139
140impl From<UserApi> for UserSummary {
141    fn from(api: UserApi) -> Self {
142        Self {
143            login: api.login,
144            id: api.id.unwrap_or_default(),
145        }
146    }
147}
148
149/// gitcode CLI `issue comment --json` 的响应类型,兼容两种已观测形态:
150/// - v0.6.x:`user` 为对象(含 `login`/`id`)、`id` 为数值、`created_at` 为带偏移 RFC3339
151/// - 旧版本:`author` 为纯字符串(用户名)、`id` 为字符串、`created_at` 为 `YYYY-MM-DD HH:MM:SS`
152#[derive(Debug, Clone, Deserialize)]
153struct CommentApiResponse {
154    #[serde(deserialize_with = "gitflow_core::types::deserialize_u64_or_string")]
155    id: u64,
156    #[serde(default)]
157    body: String,
158    #[serde(default)]
159    author: Option<String>,
160    #[serde(default)]
161    user: Option<UserApi>,
162    #[serde(default)]
163    created_at: Option<String>,
164}
165
166impl From<CommentApiResponse> for CommentData {
167    fn from(api: CommentApiResponse) -> Self {
168        let author = api.user.map_or_else(
169            || UserSummary {
170                login: api.author.unwrap_or_else(|| "unknown".into()),
171                id: String::new(),
172            },
173            UserSummary::from,
174        );
175        let created_at = api.created_at.as_deref().and_then(|s| {
176            DateTime::parse_from_rfc3339(s)
177                .map(|dt| dt.with_timezone(&Utc))
178                .or_else(|_| {
179                    chrono::NaiveDateTime::parse_from_str(s, "%Y-%m-%d %H:%M:%S")
180                        .map(|ndt| ndt.and_utc())
181                })
182                .ok()
183        });
184        Self {
185            id: api.id,
186            body: api.body,
187            author,
188            created_at,
189        }
190    }
191}
192
193/// gitcode CLI `issue close/reopen --json` 的响应类型。
194///
195/// 只是一个精简确认对象——实测响应(2026-09-21,对 byx-darwin/NexaTrade 的
196/// 真实 issue #3)为 `{"number":3,"state":"closed","owner":"...","repo":"...","url":"..."}`,
197/// 没有 `title`/`body`/`created_at`/`milestone` 等字段。只需要 `number` 去调用
198/// `view()` 拿完整数据,其余字段不建模,避免死代码。
199#[derive(Debug, Clone, Deserialize)]
200struct CloseApiResponse {
201    number: u64,
202}
203
204/// GitCode Issue 提供者,通过 `gitcode` CLI 操作。
205///
206/// 命令执行通过 [`CommandRunner`] 抽象,生产环境默认使用
207/// [`RealCommandRunner`],测试可注入自定义 runner 以模拟成功或失败场景。
208#[derive(Debug, Clone)]
209pub struct GitCodeIssueProvider<R: CommandRunner = RealCommandRunner> {
210    /// GitCode `owner/repo`。
211    repo: String,
212    /// 用于执行 `gitcode` CLI 命令的 runner。
213    runner: R,
214}
215
216impl GitCodeIssueProvider<RealCommandRunner> {
217    /// 创建一个新的 `GitCodeIssueProvider`,使用真实的进程执行器。
218    #[must_use]
219    pub fn new(repo: impl Into<String>) -> Self {
220        Self {
221            repo: repo.into(),
222            runner: RealCommandRunner,
223        }
224    }
225
226    /// Create a new provider from a shared [`Session`].
227    ///
228    /// This enables state reuse across multiple operations in workflow chains.
229    #[must_use]
230    pub fn with_session(session: &Session) -> Self {
231        Self {
232            repo: session.repo.clone(),
233            runner: RealCommandRunner,
234        }
235    }
236}
237
238impl<R: CommandRunner> GitCodeIssueProvider<R> {
239    /// 使用自定义 [`CommandRunner`] 创建提供者。
240    ///
241    /// 主要用于测试,可注入模拟 runner 以控制 `gitcode` CLI 的输出。
242    #[must_use]
243    pub fn with_runner(repo: impl Into<String>, runner: R) -> Self {
244        Self {
245            repo: repo.into(),
246            runner,
247        }
248    }
249
250    /// 创建缺失的标签(使用 `--force` 保持幂等)。
251    ///
252    /// # Errors
253    ///
254    /// 当 `gitcode label create` 调用失败时返回错误。
255    async fn ensure_label_exists(&self, name: &str) -> Result<()> {
256        let binary = crate::gitcode_binary();
257        debug!(repo = %self.repo, name, "auto-creating missing label via `gc label create`");
258
259        let output = self
260            .runner
261            .run(
262                &binary,
263                &[
264                    "label", "create", name, "--color", "ededed", "-R", &self.repo,
265                ],
266            )
267            .await
268            .map_err(|e| {
269                CoreError::Platform(format!("Failed to spawn gitcode label create: {e}"))
270            })?;
271
272        if !output.status.success() {
273            let gitcode_err = parse_gitcode_error(&output.stderr);
274            tracing::debug!(error = %gitcode_err, "Failed to auto-create label");
275            return Err(CoreError::Platform(format!(
276                "Failed to auto-create label '{name}': {}",
277                gitcode_err.user_message
278            )));
279        }
280
281        Ok(())
282    }
283}
284
285impl<R: CommandRunner + Clone + 'static> GitCodeIssueProvider<R> {
286    /// [`IssueProvider::list`] 的实际实现。
287    ///
288    /// 抽成普通(非 `async_trait` 装箱)的关联函数,避开泛型异步闭包在
289    /// `async_trait` 装箱 Future 内部触发的 HRTB `Send` 检查缺陷。
290    async fn list_impl(&self, args: ListIssueArgs) -> Result<Paged<IssueData>> {
291        let binary = crate::gitcode_binary();
292        let binary = &binary;
293        let cap = args.limit.unwrap_or(DEFAULT_LIST_LIMIT);
294        let repo = &self.repo;
295        let runner = &self.runner;
296        let state = args.state;
297        let search = &args.search;
298        let labels = &args.labels;
299        let milestone = &args.milestone;
300        // 实测(gitcode-cli 0.12.0):`--per-page` 优先于 `--limit`,且被 API
301        // 静默封顶在 100;`--page` 真实翻页,页间编号不重叠。页大小不必超过
302        // cap+1:N+1 探测只需多要一条即可判断截断。
303        let per_page = cap.saturating_add(1).min(crate::GITCODE_API_MAX_PER_PAGE);
304
305        debug!(repo = %self.repo, cap, per_page, "spawning gitcode issue list");
306
307        fetch_capped(
308            FetchStrategy::Paged { per_page },
309            cap,
310            |page, per_page| async move {
311                let page_str = page.to_string();
312                let per_page_str = per_page.to_string();
313                let mut cmd_args: Vec<&str> = vec!["issue", "list", "-R", repo, "--json"];
314
315                if let Some(state) = &state {
316                    cmd_args.push("--state");
317                    cmd_args.push(match state {
318                        State::Open => "open",
319                        State::Closed => "closed",
320                        State::All => "all",
321                    });
322                }
323                if let Some(search) = search {
324                    cmd_args.push("--search");
325                    cmd_args.push(search);
326                }
327                for label in labels {
328                    cmd_args.push("--label");
329                    cmd_args.push(label);
330                }
331                let resolved_milestone_number_str;
332                if let Some(identifier) = milestone {
333                    let milestone_provider =
334                        crate::GitCodeMilestoneProvider::with_runner(repo.as_str(), runner.clone());
335                    let resolved = gitflow_core::label::resolve_milestone_identifier(
336                        &milestone_provider,
337                        identifier,
338                    )
339                    .await?;
340                    resolved_milestone_number_str = resolved.number.to_string();
341                    cmd_args.push("--milestone");
342                    cmd_args.push(&resolved_milestone_number_str);
343                }
344                cmd_args.push("--per-page");
345                cmd_args.push(&per_page_str);
346                cmd_args.push("--page");
347                cmd_args.push(&page_str);
348
349                let output = runner
350                    .run(binary, &cmd_args)
351                    .await
352                    .map_err(|e| CoreError::Platform(format!("{e}")))?;
353                if !output.status.success() {
354                    return Err(parse_gitcode_error(&output.stderr).into());
355                }
356                let issues: Vec<IssueApiResponse> =
357                    serde_json::from_slice(&output.stdout).map_err(CoreError::Serialization)?;
358                Ok(issues.into_iter().map(IssueData::from).collect())
359            },
360        )
361        .await
362    }
363}
364
365#[async_trait]
366impl<R: CommandRunner + Clone + 'static> IssueProvider for GitCodeIssueProvider<R> {
367    async fn create(&self, args: CreateIssueArgs) -> Result<IssueData> {
368        let binary = crate::gitcode_binary();
369        let mut cmd_args: Vec<&str> = vec![
370            "issue",
371            "create",
372            "-R",
373            &self.repo,
374            "--title",
375            &args.title,
376            "--json",
377        ];
378
379        if let Some(body) = &args.body {
380            cmd_args.push("--body");
381            cmd_args.push(body);
382        }
383        for label in &args.labels {
384            cmd_args.push("--label");
385            cmd_args.push(label);
386        }
387        for assignee in &args.assignees {
388            cmd_args.push("--assignee");
389            cmd_args.push(assignee);
390        }
391
392        let resolved_milestone_number_str;
393        if let Some(identifier) = &args.milestone {
394            let milestone_provider = crate::GitCodeMilestoneProvider::with_runner(
395                self.repo.as_str(),
396                self.runner.clone(),
397            );
398            let resolved =
399                gitflow_core::label::resolve_milestone_identifier(&milestone_provider, identifier)
400                    .await?;
401            resolved_milestone_number_str = resolved.number.to_string();
402            cmd_args.push("--milestone");
403            cmd_args.push(&resolved_milestone_number_str);
404        }
405
406        debug!(repo = %self.repo, title = %args.title, "spawning gitcode issue create");
407        let output = self
408            .runner
409            .run(&binary, &cmd_args)
410            .await
411            .map_err(|e| CoreError::Platform(format!("{e}")))?;
412        if !output.status.success() {
413            // gc issue create fails when a requested label doesn't exist.
414            // Auto-create missing labels and retry once.
415            let missing = extract_missing_labels_from_error(&output.stderr);
416            if !missing.is_empty() {
417                debug!(
418                    repo = %self.repo,
419                    missing_count = missing.len(),
420                    "auto-creating missing label(s) before retrying issue create"
421                );
422                for label in &missing {
423                    self.ensure_label_exists(label).await?;
424                }
425
426                let retry_output = self.runner.run(&binary, &cmd_args).await.map_err(|e| {
427                    CoreError::Platform(format!("Failed to spawn gitcode on retry: {e}"))
428                })?;
429                if !retry_output.status.success() {
430                    return Err(parse_gitcode_error(&retry_output.stderr).into());
431                }
432                return serde_json::from_slice::<IssueApiResponse>(&retry_output.stdout)
433                    .map(IssueData::from)
434                    .map_err(CoreError::Serialization);
435            }
436
437            return Err(parse_gitcode_error(&output.stderr).into());
438        }
439        serde_json::from_slice::<IssueApiResponse>(&output.stdout)
440            .map(IssueData::from)
441            .map_err(CoreError::Serialization)
442    }
443
444    /// 编辑 Issue 的标题和/或正文。
445    ///
446    /// 调用 `<gitcode_binary> issue edit <number> -R <repo> [--title T] [--body B]`,
447    /// 成功后通过 [`view`](Self::view) 重新拉取最新数据并返回(不解析 `edit` 自身的
448    /// stdout,避免依赖未经验证的响应结构)。
449    ///
450    /// # Errors
451    ///
452    /// 当 Issue 不存在或 `gitcode` CLI 调用失败时返回错误。
453    async fn edit(&self, number: u64, args: EditIssueArgs) -> Result<IssueData> {
454        let binary = crate::gitcode_binary();
455        let number_str = number.to_string();
456        debug!(repo = %self.repo, number, "spawning gitcode issue edit");
457
458        let mut cmd_args: Vec<&str> = vec!["issue", "edit", &number_str, "-R", &self.repo];
459        if let Some(title) = &args.title {
460            cmd_args.push("--title");
461            cmd_args.push(title);
462        }
463        if let Some(body) = &args.body {
464            cmd_args.push("--body");
465            cmd_args.push(body);
466        }
467
468        let resolved_milestone_number_str;
469        match &args.milestone {
470            None => {}
471            Some(None) => {
472                // 实测(2026-09-21 对 byx-darwin/NexaTrade issue #1):`gitcode
473                // issue edit --milestone 0` 被 CLI 解析层当作"未设置"直接拒绝
474                // ("at least one edit option is required");`--milestone -1`
475                // 会被后端静默丢弃而不是清除里程碑——`edit` 响应本身回显
476                // milestone: null,但紧随其后的 `issue view` 仍显示原里程碑未变。
477                // GitCode CLI 没有任何取消关联里程碑的手段,诚实报错而非假装成功。
478                return Err(gitflow_core::CoreError::Platform(
479                    "GitCode CLI does not support unassigning a milestone from an issue".into(),
480                ));
481            }
482            Some(Some(identifier)) => {
483                let milestone_provider = crate::GitCodeMilestoneProvider::with_runner(
484                    self.repo.as_str(),
485                    self.runner.clone(),
486                );
487                let resolved = gitflow_core::label::resolve_milestone_identifier(
488                    &milestone_provider,
489                    identifier,
490                )
491                .await?;
492                resolved_milestone_number_str = resolved.number.to_string();
493                cmd_args.push("--milestone");
494                cmd_args.push(&resolved_milestone_number_str);
495            }
496        }
497
498        let output = self
499            .runner
500            .run(&binary, &cmd_args)
501            .await
502            .map_err(|e| CoreError::Platform(format!("{e}")))?;
503
504        if !output.status.success() {
505            return Err(parse_gitcode_error(&output.stderr).into());
506        }
507
508        self.view(number).await
509    }
510
511    async fn list(&self, args: ListIssueArgs) -> Result<Paged<IssueData>> {
512        self.list_impl(args).await
513    }
514
515    async fn view(&self, number: u64) -> Result<IssueData> {
516        let binary = crate::gitcode_binary();
517        let number_str = number.to_string();
518        debug!(repo = %self.repo, number, "spawning gitcode issue view");
519        let output = self
520            .runner
521            .run(
522                &binary,
523                &["issue", "view", &number_str, "-R", &self.repo, "--json"],
524            )
525            .await
526            .map_err(|e| CoreError::Platform(format!("{e}")))?;
527
528        if !output.status.success() {
529            return Err(parse_gitcode_error(&output.stderr).into());
530        }
531        serde_json::from_slice::<IssueApiResponse>(&output.stdout)
532            .map(IssueData::from)
533            .map_err(CoreError::Serialization)
534    }
535
536    async fn close(&self, number: u64) -> Result<IssueData> {
537        let binary = crate::gitcode_binary();
538        let number_str = number.to_string();
539        debug!(repo = %self.repo, number, "spawning gitcode issue close");
540        let output = self
541            .runner
542            .run(
543                &binary,
544                &[
545                    "issue",
546                    "close",
547                    &number_str,
548                    "-R",
549                    &self.repo,
550                    "--yes",
551                    "--json",
552                ],
553            )
554            .await
555            .map_err(|e| CoreError::Platform(format!("{e}")))?;
556
557        if !output.status.success() {
558            return Err(parse_gitcode_error(&output.stderr).into());
559        }
560        let close_result: CloseApiResponse =
561            serde_json::from_slice(&output.stdout).map_err(CoreError::Serialization)?;
562        self.view(close_result.number).await
563    }
564
565    async fn reopen(&self, number: u64) -> Result<IssueData> {
566        let binary = crate::gitcode_binary();
567        let number_str = number.to_string();
568        debug!(repo = %self.repo, number, "spawning gitcode issue reopen");
569        let output = self
570            .runner
571            .run(
572                &binary,
573                &[
574                    "issue",
575                    "reopen",
576                    &number_str,
577                    "-R",
578                    &self.repo,
579                    "--yes",
580                    "--json",
581                ],
582            )
583            .await
584            .map_err(|e| CoreError::Platform(format!("{e}")))?;
585
586        if !output.status.success() {
587            return Err(parse_gitcode_error(&output.stderr).into());
588        }
589        let reopen_result: CloseApiResponse =
590            serde_json::from_slice(&output.stdout).map_err(CoreError::Serialization)?;
591        self.view(reopen_result.number).await
592    }
593
594    /// 在指定 Issue 上添加评论。
595    ///
596    /// 调用 `gitcode issue comment <number> -R <repo> --body "<body>" --json`
597    /// 发布评论,并返回新建评论的数据。
598    ///
599    /// # Errors
600    ///
601    /// 当 Issue 不存在、`body` 为空或 `gitcode` CLI 调用失败时返回错误。
602    async fn comment(&self, number: u64, body: &str) -> Result<CommentData> {
603        let binary = crate::gitcode_binary();
604        let number_str = number.to_string();
605        debug!(repo = %self.repo, number, "spawning `gc issue comment`");
606
607        let output = self
608            .runner
609            .run(
610                &binary,
611                &[
612                    "issue",
613                    "comment",
614                    &number_str,
615                    "-R",
616                    &self.repo,
617                    "--body",
618                    body,
619                    "--json",
620                ],
621            )
622            .await
623            .map_err(|e| CoreError::Platform(format!("Failed to spawn gitcode: {e}")))?;
624
625        if !output.status.success() {
626            return Err(parse_gitcode_error(&output.stderr).into());
627        }
628
629        let api: CommentApiResponse =
630            serde_json::from_slice(&output.stdout).map_err(CoreError::Serialization)?;
631
632        Ok(CommentData::from(api))
633    }
634
635    /// 列出指定 Issue 的评论。
636    ///
637    /// 调用 `gitcode api /repos/{owner}/{repo}/issues/{number}/comments` 获取评论列表,
638    /// 通过 `per_page`/`page` 查询参数逐页取到 `limit`。
639    ///
640    /// GitCode CLI 的 `api` 子命令是否支持这两个查询参数**未经实测**(本环境
641    /// 无法获取 GitCode CLI 二进制)。若平台忽略它们,首页会短于 `per_page`,
642    /// 翻页循环在第一次调用后即因短页而终止——退化为今天「只取首页」的行为,
643    /// 不会死循环也不会丢数据。
644    ///
645    /// # Errors
646    ///
647    /// 当 Issue 不存在或 `gitcode` CLI 调用失败时返回错误。
648    async fn list_comments(&self, number: u64, limit: Option<u32>) -> Result<Paged<CommentData>> {
649        let cap = limit.unwrap_or(DEFAULT_LIST_LIMIT);
650        let binary = crate::gitcode_binary();
651        let binary = &binary;
652        let repo = &self.repo;
653        let runner = &self.runner;
654        let per_page = cap.saturating_add(1).min(crate::GITCODE_API_MAX_PER_PAGE);
655
656        debug!(repo = %self.repo, number, cap, "spawning `gitcode api` GET issue comments");
657
658        fetch_capped(
659            FetchStrategy::Paged { per_page },
660            cap,
661            |page, per_page| async move {
662                let api_path = format!(
663                    "/repos/{repo}/issues/{number}/comments?per_page={per_page}&page={page}"
664                );
665
666                let output = runner.run(binary, &["api", &api_path]).await.map_err(|e| {
667                    CoreError::Platform(format!("Failed to spawn gitcode api: {e}"))
668                })?;
669
670                if !output.status.success() {
671                    return Err(parse_gitcode_error(&output.stderr).into());
672                }
673
674                let comments: Vec<CommentApiResponse> =
675                    serde_json::from_slice(&output.stdout).map_err(CoreError::Serialization)?;
676                Ok(comments.into_iter().map(CommentData::from).collect())
677            },
678        )
679        .await
680    }
681
682    /// 为指定 Issue 添加一个或多个标签。
683    ///
684    /// 调用 `gitcode issue label <number> --add <labels> -R <repo>` 添加标签
685    ///(逗号分隔的 `--add` 是 gitcode v0.6.x 的专用标签子命令;`issue edit`
686    /// 不支持 gh 风格的 `--add-label` flag)。`labels` 为空时不进行任何调用。
687    ///
688    /// # 自动创建缺失标签
689    ///
690    /// 当添加因标签不存在而失败时,本方法会自动调用 `gitcode label create`
691    /// 创建缺失的标签(默认颜色 `ededed`),然后重试一次。
692    ///
693    /// # Errors
694    ///
695    /// 当 Issue 不存在、标签创建失败或 `gitcode` CLI 调用失败时返回错误。
696    async fn add_labels(&self, number: u64, labels: &[String]) -> Result<()> {
697        if labels.is_empty() {
698            return Ok(());
699        }
700
701        let binary = crate::gitcode_binary();
702        let number_str = number.to_string();
703        let joined = labels.join(",");
704        debug!(
705            repo = %self.repo,
706            number,
707            label_count = labels.len(),
708            "spawning `gitcode issue label --add`"
709        );
710
711        let cmd_args: Vec<&str> = vec![
712            "issue",
713            "label",
714            &number_str,
715            "--add",
716            &joined,
717            "-R",
718            &self.repo,
719        ];
720
721        let output = self
722            .runner
723            .run(&binary, &cmd_args)
724            .await
725            .map_err(|e| CoreError::Platform(format!("Failed to spawn gitcode: {e}")))?;
726
727        if output.status.success() {
728            return Ok(());
729        }
730
731        // Auto-create missing labels and retry once.
732        let missing = extract_missing_labels_from_error(&output.stderr);
733        if missing.is_empty() {
734            return Err(parse_gitcode_error(&output.stderr).into());
735        }
736
737        debug!(
738            repo = %self.repo,
739            missing_count = missing.len(),
740            "auto-creating missing label(s) before retry"
741        );
742
743        for label in &missing {
744            self.ensure_label_exists(label).await?;
745        }
746
747        let retry_output =
748            self.runner.run(&binary, &cmd_args).await.map_err(|e| {
749                CoreError::Platform(format!("Failed to spawn gitcode on retry: {e}"))
750            })?;
751
752        if !retry_output.status.success() {
753            return Err(parse_gitcode_error(&retry_output.stderr).into());
754        }
755
756        Ok(())
757    }
758
759    /// 从指定 Issue 移除一个标签。
760    ///
761    /// 调用 `gitcode issue label <number> --remove <label> -R <repo>` 移除标签。
762    ///
763    /// # Errors
764    ///
765    /// 当 Issue 不存在、标签未附加到该 Issue 或 `gitcode` CLI 调用失败时返回错误。
766    async fn remove_label(&self, number: u64, label: &str) -> Result<()> {
767        let binary = crate::gitcode_binary();
768        let number_str = number.to_string();
769        debug!(repo = %self.repo, number, label, "spawning `gitcode issue label --remove`");
770
771        let output = self
772            .runner
773            .run(
774                &binary,
775                &[
776                    "issue",
777                    "label",
778                    &number_str,
779                    "--remove",
780                    label,
781                    "-R",
782                    &self.repo,
783                ],
784            )
785            .await
786            .map_err(|e| CoreError::Platform(format!("Failed to spawn gitcode: {e}")))?;
787
788        if !output.status.success() {
789            return Err(parse_gitcode_error(&output.stderr).into());
790        }
791
792        Ok(())
793    }
794}
795
796/// 从 `gc issue label --add` 的 stderr 中提取缺失的标签名。
797///
798/// GitCode CLI 是 `gh` 的分支,错误格式与 `gh` 一致:
799/// `'<label>' not found`。
800fn extract_missing_labels_from_error(stderr: &[u8]) -> Vec<String> {
801    let text = String::from_utf8_lossy(stderr);
802    let mut labels = Vec::new();
803    let mut search_from: usize = 0;
804
805    while let Some(rel_open) = text[search_from..].find('\'') {
806        let open_pos = search_from + rel_open + 1;
807        let Some(rel_close) = text[open_pos..].find('\'') else {
808            break;
809        };
810        let close_pos = open_pos + rel_close;
811        let after_close = &text[close_pos + 1..];
812
813        if after_close.starts_with(" not found") {
814            let label = text[open_pos..close_pos].to_string();
815            if !label.is_empty() {
816                labels.push(label);
817            }
818        }
819        search_from = close_pos + 1;
820    }
821
822    labels
823}
824
825#[cfg(test)]
826mod tests {
827    use gitflow_core::types::UserSummary;
828
829    use super::*;
830    use crate::runner::{MockCommandRunner, RecordingMockRunner, SequencedMockCommandRunner};
831
832    #[test]
833    fn test_should_construct_gitcode_issue_provider() {
834        let provider = GitCodeIssueProvider::new("octocat/hello-world");
835        assert_eq!(provider.repo, "octocat/hello-world");
836    }
837
838    #[test]
839    fn test_should_construct_gitcode_issue_provider_from_string() {
840        let repo = String::from("octocat/hello-world");
841        let provider = GitCodeIssueProvider::new(repo);
842        assert_eq!(provider.repo, "octocat/hello-world");
843    }
844
845    #[test]
846    fn test_should_deserialize_issue_data_from_gc_output() {
847        let gc_json = br#"{
848            "number": 42,
849            "title": "Fix login bug",
850            "body": "Reproduced on v1.2.3",
851            "state": "open",
852            "labels": [
853                {"name": "bug", "color": "d73a4a", "description": "Something isn't working"}
854            ],
855            "author": {"login": "octocat", "id": "1"},
856            "assignees": [{"login": "alice", "id": "7"}],
857            "createdAt": "2026-01-15T09:30:00Z",
858            "updatedAt": "2026-01-16T11:00:00Z",
859            "url": "https://gitcode.com/octocat/hello-world/issues/42"
860        }"#;
861
862        let issue: IssueData = serde_json::from_slice(gc_json).expect("valid IssueData JSON");
863        assert_eq!(issue.number, 42);
864        assert_eq!(issue.title, "Fix login bug");
865        assert_eq!(issue.state, State::Open);
866        assert_eq!(issue.labels.len(), 1);
867        assert_eq!(issue.author.login, "octocat");
868        assert_eq!(issue.assignees.len(), 1);
869        assert_eq!(
870            issue.url,
871            "https://gitcode.com/octocat/hello-world/issues/42"
872        );
873    }
874
875    #[test]
876    fn test_should_keep_issue_created_at_none_when_gc_api_omits_it() {
877        let gc_json = br#"{
878            "number": "15",
879            "title": "No timestamps",
880            "body": null,
881            "state": "open",
882            "labels": [],
883            "author": {"login": "dev", "id": "5"},
884            "assignees": [],
885            "html_url": "https://gitcode.com/octocat/hello-world/issues/15"
886        }"#;
887
888        let api: IssueApiResponse =
889            serde_json::from_slice(gc_json).expect("valid IssueApiResponse");
890        let issue: IssueData = api.into();
891        assert!(
892            issue.created_at.is_none(),
893            "missing created_at must stay None, not fall back to Utc::now()"
894        );
895        assert!(
896            issue.updated_at.is_none(),
897            "missing updated_at must stay None, not fall back to Utc::now()"
898        );
899    }
900
901    #[test]
902    fn test_should_keep_comment_created_at_none_when_gc_api_omits_it() {
903        let gc_json = br#"{
904            "id": "1002",
905            "body": "No timestamp provided.",
906            "author": "maintainer"
907        }"#;
908
909        let api: CommentApiResponse =
910            serde_json::from_slice(gc_json).expect("valid CommentApiResponse");
911        let comment = CommentData::from(api);
912        assert!(
913            comment.created_at.is_none(),
914            "missing created_at must stay None, not fall back to Utc::now()"
915        );
916    }
917
918    #[test]
919    fn test_should_deserialize_empty_issue_list_from_gc_output() {
920        let gc_json = b"[]";
921        let issues: Vec<IssueData> = serde_json::from_slice(gc_json).expect("valid IssueData list");
922        assert!(issues.is_empty());
923    }
924
925    #[test]
926    fn test_should_debug_format_provider() {
927        let provider = GitCodeIssueProvider::new("octocat/hello-world");
928        let debug = format!("{provider:?}");
929        assert!(debug.contains("GitCodeIssueProvider"));
930        assert!(debug.contains("octocat/hello-world"));
931    }
932
933    #[test]
934    fn test_should_deserialize_closed_issue_from_gc_close_output() {
935        let gc_json = br#"{
936            "number": 10,
937            "title": "Fixed typo",
938            "body": null,
939            "state": "closed",
940            "labels": [],
941            "author": {"login": "dev", "id": "5"},
942            "assignees": [],
943            "createdAt": "2026-06-01T08:00:00Z",
944            "updatedAt": "2026-06-02T12:00:00Z",
945            "url": "https://gitcode.com/octocat/hello-world/issues/10"
946        }"#;
947
948        let issue: IssueData = serde_json::from_slice(gc_json).expect("valid closed IssueData");
949        assert_eq!(issue.number, 10);
950        assert_eq!(issue.state, State::Closed);
951    }
952
953    #[test]
954    fn test_should_deserialize_reopened_issue_from_gc_reopen_output() {
955        let gc_json = br#"{
956            "number": 10,
957            "title": "Fixed typo",
958            "body": null,
959            "state": "open",
960            "labels": [],
961            "author": {"login": "dev", "id": "5"},
962            "assignees": [],
963            "createdAt": "2026-06-01T08:00:00Z",
964            "updatedAt": "2026-06-03T09:00:00Z",
965            "url": "https://gitcode.com/octocat/hello-world/issues/10"
966        }"#;
967
968        let issue: IssueData = serde_json::from_slice(gc_json).expect("valid reopened IssueData");
969        assert_eq!(issue.number, 10);
970        assert_eq!(issue.state, State::Open);
971    }
972
973    #[test]
974    fn test_should_deserialize_comment_data_from_gc_comment_output() {
975        let gc_json = br#"{
976            "id": "1001",
977            "body": "Thanks for reporting, looking into it.",
978            "author": "maintainer",
979            "created_at": "2026-06-15 14:00:00"
980        }"#;
981
982        let api: CommentApiResponse =
983            serde_json::from_slice(gc_json).expect("valid CommentApiResponse");
984        let comment = CommentData::from(api);
985        assert_eq!(comment.id, 1001);
986        assert_eq!(comment.body, "Thanks for reporting, looking into it.");
987        assert_eq!(comment.author.login, "maintainer");
988    }
989
990    #[test]
991    fn test_should_roundtrip_comment_data_via_serde() {
992        let comment = CommentData {
993            id: 77,
994            body: "reviewed".into(),
995            author: UserSummary {
996                login: "alice".into(),
997                id: "3".to_string(),
998            },
999            created_at: Some("2026-05-01T00:00:00Z".parse().expect("valid date")),
1000        };
1001        let json = serde_json::to_string(&comment).expect("serialize");
1002        let round_tripped: CommentData = serde_json::from_str(&json).expect("deserialize");
1003        assert_eq!(round_tripped.id, comment.id);
1004        assert_eq!(round_tripped.body, comment.body);
1005        assert_eq!(round_tripped.author.login, comment.author.login);
1006    }
1007
1008    #[test]
1009    fn test_should_create_provider_with_different_repos() {
1010        let r1 = GitCodeIssueProvider::new("org/repo-a");
1011        let r2 = GitCodeIssueProvider::new("org/repo-b");
1012        assert_eq!(r1.repo, "org/repo-a");
1013        assert_eq!(r2.repo, "org/repo-b");
1014    }
1015
1016    #[test]
1017    fn test_should_clone_gitcode_issue_provider() {
1018        let original = GitCodeIssueProvider::new("owner/repo");
1019        let cloned = original.clone();
1020        assert_eq!(original.repo, cloned.repo);
1021    }
1022
1023    // --- Failure-path tests using an injected MockCommandRunner ---
1024
1025    fn sample_create_args() -> CreateIssueArgs {
1026        CreateIssueArgs {
1027            title: "Bug report".to_string(),
1028            body: Some("Steps to reproduce".to_string()),
1029            labels: vec!["bug".to_string()],
1030            assignees: vec!["alice".to_string()],
1031            milestone: None,
1032        }
1033    }
1034
1035    #[tokio::test]
1036    async fn test_should_return_platform_error_when_gc_fails_for_view() {
1037        let runner = MockCommandRunner::failure("issue not found", 256);
1038        let provider = GitCodeIssueProvider::with_runner("owner/repo", runner);
1039
1040        let result = provider.view(999).await;
1041
1042        assert!(matches!(
1043            result.unwrap_err(),
1044            gitflow_core::CoreError::Cli(_)
1045        ));
1046    }
1047
1048    #[tokio::test]
1049    async fn test_should_return_serialization_error_on_invalid_json_for_view() {
1050        let runner = MockCommandRunner::success("not valid json");
1051        let provider = GitCodeIssueProvider::with_runner("owner/repo", runner);
1052
1053        let result = provider.view(1).await;
1054
1055        assert!(matches!(
1056            result.unwrap_err(),
1057            gitflow_core::CoreError::Serialization(_)
1058        ));
1059    }
1060
1061    #[tokio::test]
1062    async fn test_should_return_platform_error_when_gc_fails_for_list() {
1063        let runner = MockCommandRunner::failure("forbidden", 256);
1064        let provider = GitCodeIssueProvider::with_runner("owner/repo", runner);
1065
1066        let result = provider.list(ListIssueArgs::default()).await;
1067
1068        assert!(matches!(
1069            result.unwrap_err(),
1070            gitflow_core::CoreError::Cli(_)
1071        ));
1072    }
1073
1074    #[tokio::test]
1075    async fn test_should_return_serialization_error_on_invalid_json_for_list() {
1076        let runner = MockCommandRunner::success("invalid");
1077        let provider = GitCodeIssueProvider::with_runner("owner/repo", runner);
1078
1079        let result = provider.list(ListIssueArgs::default()).await;
1080
1081        assert!(matches!(
1082            result.unwrap_err(),
1083            gitflow_core::CoreError::Serialization(_)
1084        ));
1085    }
1086
1087    #[tokio::test]
1088    async fn test_should_return_platform_error_when_gc_fails_for_create() {
1089        let runner = MockCommandRunner::failure("validation failed", 256);
1090        let provider = GitCodeIssueProvider::with_runner("owner/repo", runner);
1091
1092        let result = provider.create(sample_create_args()).await;
1093
1094        assert!(matches!(
1095            result.unwrap_err(),
1096            gitflow_core::CoreError::Cli(_)
1097        ));
1098    }
1099
1100    #[tokio::test]
1101    async fn test_should_return_serialization_error_on_invalid_json_for_create() {
1102        let runner = MockCommandRunner::success("not valid json");
1103        let provider = GitCodeIssueProvider::with_runner("owner/repo", runner);
1104
1105        let result = provider.create(sample_create_args()).await;
1106
1107        assert!(matches!(
1108            result.unwrap_err(),
1109            gitflow_core::CoreError::Serialization(_)
1110        ));
1111    }
1112
1113    #[tokio::test]
1114    async fn test_should_close_then_view_to_get_full_issue_with_milestone() {
1115        // 实测响应(2026-09-21,对 byx-darwin/NexaTrade 的真实 issue #3):
1116        // `gitcode issue close --json` 只返回精简确认对象(number/state/owner/repo/url),
1117        // 没有 title/created_at/updated_at/milestone。close() 必须用这个精简形状拿到
1118        // number,再调用 view() 取回完整、正确的 IssueData(而不是伪造 title=""、
1119        // created_at=now() 并丢弃 milestone)。
1120        let runner = SequencedMockCommandRunner::from_results(&[
1121            (
1122                true,
1123                r#"{"number":3,"state":"closed","owner":"byx-darwin","repo":"NexaTrade","url":"https://gitcode.com/byx-darwin/NexaTrade/issues/3"}"#,
1124            ),
1125            (
1126                true,
1127                r#"{"number":"3","title":"Real title","body":"real body","state":"closed","labels":[],"user":{"login":"octocat","id":"1"},"assignees":[],"created_at":"2026-01-01T00:00:00Z","updated_at":"2026-01-02T00:00:00Z","html_url":"https://gitcode.com/owner/repo/issues/3","milestone":{"number":7,"title":"v3.0"}}"#,
1128            ),
1129        ]);
1130        let provider = GitCodeIssueProvider::with_runner("owner/repo", runner.clone());
1131
1132        let issue = provider.close(3).await.expect("close should succeed");
1133
1134        // 标题/时间戳来自第二次(view)响应,证明确实走了 view 而非直接转换精简响应
1135        assert_eq!(issue.number, 3);
1136        assert_eq!(issue.title, "Real title");
1137        assert_eq!(issue.body.as_deref(), Some("real body"));
1138        assert_eq!(
1139            issue.created_at.map(|dt| dt.to_rfc3339()),
1140            Some("2026-01-01T00:00:00+00:00".to_string())
1141        );
1142        assert_eq!(
1143            issue.milestone,
1144            Some(gitflow_core::types::MilestoneRef {
1145                number: 7,
1146                title: "v3.0".into(),
1147            })
1148        );
1149        let calls = runner.recorded_calls();
1150        assert_eq!(calls.len(), 2, "close 必须先 close 再 view 两次调用");
1151        assert!(calls[0].1.contains(&"close".to_string()));
1152        assert!(calls[1].1.contains(&"view".to_string()));
1153    }
1154
1155    #[tokio::test]
1156    async fn test_should_reopen_then_view_to_get_full_issue_with_milestone() {
1157        let runner = SequencedMockCommandRunner::from_results(&[
1158            (
1159                true,
1160                r#"{"number":3,"state":"open","owner":"byx-darwin","repo":"NexaTrade","url":"https://gitcode.com/byx-darwin/NexaTrade/issues/3"}"#,
1161            ),
1162            (
1163                true,
1164                r#"{"number":"3","title":"Real title","body":null,"state":"open","labels":[],"user":{"login":"octocat","id":"1"},"assignees":[],"created_at":"2026-01-01T00:00:00Z","updated_at":"2026-01-02T00:00:00Z","html_url":"https://gitcode.com/owner/repo/issues/3","milestone":{"number":7,"title":"v3.0"}}"#,
1165            ),
1166        ]);
1167        let provider = GitCodeIssueProvider::with_runner("owner/repo", runner.clone());
1168
1169        let issue = provider.reopen(3).await.expect("reopen should succeed");
1170
1171        assert_eq!(issue.number, 3);
1172        assert_eq!(issue.title, "Real title");
1173        assert_eq!(
1174            issue.milestone,
1175            Some(gitflow_core::types::MilestoneRef {
1176                number: 7,
1177                title: "v3.0".into(),
1178            })
1179        );
1180        let calls = runner.recorded_calls();
1181        assert_eq!(calls.len(), 2, "reopen 必须先 reopen 再 view 两次调用");
1182        assert!(calls[0].1.contains(&"reopen".to_string()));
1183        assert!(calls[1].1.contains(&"view".to_string()));
1184    }
1185
1186    #[tokio::test]
1187    async fn test_should_propagate_view_error_after_issue_close_succeeds() {
1188        let runner = SequencedMockCommandRunner::from_results(&[
1189            (true, r#"{"number":3,"state":"closed"}"#),
1190            (false, "gitcode: issue not found"),
1191        ]);
1192        let provider = GitCodeIssueProvider::with_runner("owner/repo", runner);
1193
1194        let err = provider
1195            .close(3)
1196            .await
1197            .expect_err("view failure must propagate");
1198
1199        assert!(matches!(err, gitflow_core::CoreError::Cli(_)));
1200    }
1201
1202    #[tokio::test]
1203    async fn test_should_return_platform_error_when_gc_fails_for_close() {
1204        let runner = MockCommandRunner::failure("not found", 256);
1205        let provider = GitCodeIssueProvider::with_runner("owner/repo", runner);
1206
1207        let result = provider.close(42).await;
1208
1209        assert!(matches!(
1210            result.unwrap_err(),
1211            gitflow_core::CoreError::Cli(_)
1212        ));
1213    }
1214
1215    #[tokio::test]
1216    async fn test_should_return_platform_error_when_gc_fails_for_reopen() {
1217        let runner = MockCommandRunner::failure("not found", 256);
1218        let provider = GitCodeIssueProvider::with_runner("owner/repo", runner);
1219
1220        let result = provider.reopen(42).await;
1221
1222        assert!(matches!(
1223            result.unwrap_err(),
1224            gitflow_core::CoreError::Cli(_)
1225        ));
1226    }
1227
1228    #[tokio::test]
1229    async fn test_should_return_platform_error_when_gc_fails_for_comment() {
1230        let runner = MockCommandRunner::failure("not found", 256);
1231        let provider = GitCodeIssueProvider::with_runner("owner/repo", runner);
1232
1233        let result = provider.comment(42, "a comment").await;
1234
1235        assert!(matches!(
1236            result.unwrap_err(),
1237            gitflow_core::CoreError::Cli(_)
1238        ));
1239    }
1240
1241    #[tokio::test]
1242    async fn test_should_produce_complete_argv_for_list_comments_with_default_limit() {
1243        let runner = MockCommandRunner::success("[]");
1244        let provider = GitCodeIssueProvider::with_runner("owner/repo", runner.clone());
1245
1246        let paged = provider
1247            .list_comments(359, None)
1248            .await
1249            .expect("list_comments should succeed");
1250
1251        assert!(paged.items.is_empty());
1252        let calls = runner.recorded_calls();
1253        assert_eq!(calls[0].0, crate::gitcode_binary());
1254        assert_eq!(
1255            calls[0].1,
1256            vec![
1257                "api",
1258                "/repos/owner/repo/issues/359/comments?per_page=100&page=1"
1259            ]
1260        );
1261    }
1262
1263    #[tokio::test]
1264    async fn test_should_build_well_formed_query_string_for_list_comments() {
1265        let runner = MockCommandRunner::success("[]");
1266        let provider = GitCodeIssueProvider::with_runner("owner/repo", runner.clone());
1267
1268        provider
1269            .list_comments(359, None)
1270            .await
1271            .expect("list_comments should succeed");
1272
1273        let calls = runner.recorded_calls();
1274        let api_path = &calls[0].1[1];
1275        assert_eq!(
1276            api_path.matches('?').count(),
1277            1,
1278            "must have exactly one '?', got: {api_path}"
1279        );
1280        assert_eq!(
1281            api_path.matches('&').count(),
1282            1,
1283            "must have exactly one '&', got: {api_path}"
1284        );
1285        // 整串相等,而非 `contains`:`"per_page=1001".contains("per_page=100")`
1286        // 与 `"per_page=100".contains("page=1")` 都为真,子串断言无法检测出
1287        // 页大小钳位失效或页号错误——正是本测试得名的那个缺陷。
1288        assert_eq!(
1289            api_path, "/repos/owner/repo/issues/359/comments?per_page=100&page=1",
1290            "got: {api_path}"
1291        );
1292    }
1293
1294    #[tokio::test]
1295    async fn test_should_return_platform_error_when_gc_fails_for_add_labels() {
1296        let runner = MockCommandRunner::failure("not found", 256);
1297        let provider = GitCodeIssueProvider::with_runner("owner/repo", runner);
1298
1299        let result = provider.add_labels(42, &["bug".to_string()]).await;
1300
1301        assert!(matches!(
1302            result.unwrap_err(),
1303            gitflow_core::CoreError::Cli(_)
1304        ));
1305    }
1306
1307    #[tokio::test]
1308    async fn test_should_return_platform_error_when_gc_fails_for_remove_label() {
1309        let runner = MockCommandRunner::failure("not found", 256);
1310        let provider = GitCodeIssueProvider::with_runner("owner/repo", runner);
1311
1312        let result = provider.remove_label(42, "bug").await;
1313
1314        assert!(matches!(
1315            result.unwrap_err(),
1316            gitflow_core::CoreError::Cli(_)
1317        ));
1318    }
1319
1320    #[tokio::test]
1321    async fn test_should_edit_issue_and_view_result() {
1322        // Sequence: 1. `gitcode issue edit` → succeeds
1323        //           2. `gitcode issue view --json` → returns updated issue JSON
1324        let runner = SequencedMockCommandRunner::from_results(&[
1325            (true, ""),
1326            (
1327                true,
1328                r#"{"number":"42","title":"New title","body":"orig","state":"open","labels":[],"user":{"login":"octocat","id":"1"},"assignees":[],"created_at":"2026-01-01T00:00:00Z","updated_at":"2026-01-02T00:00:00Z","html_url":"https://gitcode.com/owner/repo/issues/42"}"#,
1329            ),
1330        ]);
1331        let provider = GitCodeIssueProvider::with_runner("owner/repo", runner);
1332
1333        let issue = provider
1334            .edit(
1335                42,
1336                gitflow_core::issue::EditIssueArgs {
1337                    title: Some("New title".to_string()),
1338                    body: None,
1339                    milestone: None,
1340                },
1341            )
1342            .await
1343            .expect("edit should succeed");
1344
1345        assert_eq!(issue.number, 42);
1346        assert_eq!(issue.title, "New title");
1347    }
1348
1349    #[tokio::test]
1350    async fn test_should_invoke_issue_edit_subcommand_with_provided_fields() {
1351        let runner = RecordingMockRunner::success("");
1352        let provider = GitCodeIssueProvider::with_runner("o/r", runner.clone());
1353
1354        // view() call afterward will fail on empty stdout — irrelevant to this test,
1355        // which only asserts the first (edit) call's argv.
1356        let _ = provider
1357            .edit(
1358                54,
1359                gitflow_core::issue::EditIssueArgs {
1360                    title: Some("T".to_string()),
1361                    body: Some("B".to_string()),
1362                    milestone: None,
1363                },
1364            )
1365            .await;
1366
1367        assert_eq!(
1368            runner.calls()[0],
1369            vec![
1370                "issue", "edit", "54", "-R", "o/r", "--title", "T", "--body", "B"
1371            ]
1372        );
1373    }
1374
1375    #[tokio::test]
1376    async fn test_should_return_platform_error_when_gc_fails_for_edit() {
1377        let runner = MockCommandRunner::failure("not found", 256);
1378        let provider = GitCodeIssueProvider::with_runner("owner/repo", runner);
1379
1380        let result = provider
1381            .edit(42, gitflow_core::issue::EditIssueArgs::default())
1382            .await;
1383
1384        assert!(matches!(
1385            result.unwrap_err(),
1386            gitflow_core::CoreError::Cli(_)
1387        ));
1388    }
1389
1390    // --- milestone wiring: create/edit/list ---
1391
1392    #[test]
1393    fn test_should_deserialize_issue_with_milestone() {
1394        // Real shape captured from `gitcode issue view --json` on
1395        // byx-darwin/NexaTrade issue #1 (2026-09-21), trimmed to the fields
1396        // this module reads (`id`/`description`/`state`/`due_on` ignored).
1397        let json = br#"{
1398            "number": "1",
1399            "title": "gf-357 milestone test issue",
1400            "body": "temp test issue for milestone shape investigation",
1401            "state": "open",
1402            "html_url": "https://gitcode.com/byx-darwin/NexaTrade/issues/1",
1403            "user": {"login": "byx-darwin", "id": "66767cd4096c81780c61bf07"},
1404            "assignees": [],
1405            "labels": [],
1406            "milestone": {
1407                "id": null,
1408                "number": 866493,
1409                "title": "gf-357-test-milestone",
1410                "description": "",
1411                "state": "active",
1412                "due_on": "2026-10-21"
1413            },
1414            "created_at": "2026-09-21T10:18:16+08:00",
1415            "updated_at": "2026-09-21T10:18:16+08:00"
1416        }"#;
1417        let api: IssueApiResponse = serde_json::from_slice(json).expect("deserialize");
1418        let issue: IssueData = api.into();
1419        assert_eq!(
1420            issue.milestone,
1421            Some(gitflow_core::types::MilestoneRef {
1422                number: 866_493,
1423                title: "gf-357-test-milestone".into()
1424            })
1425        );
1426    }
1427
1428    #[test]
1429    fn test_should_deserialize_issue_with_no_milestone() {
1430        let json = br#"{
1431            "number": "1",
1432            "title": "t",
1433            "body": null,
1434            "state": "open",
1435            "html_url": "https://gitcode.com/o/r/issues/1",
1436            "user": null,
1437            "assignees": [],
1438            "labels": [],
1439            "created_at": "2026-09-21T10:18:16+08:00",
1440            "updated_at": "2026-09-21T10:18:16+08:00"
1441        }"#;
1442        let api: IssueApiResponse = serde_json::from_slice(json).expect("deserialize");
1443        let issue: IssueData = api.into();
1444        assert!(issue.milestone.is_none());
1445    }
1446
1447    /// A single-item `gitcode milestone list --json` response resolving to
1448    /// number 3 / title "v2.0", matching `resolve_milestone_identifier`'s contract.
1449    fn milestone_list_fixture() -> String {
1450        r#"[{"number": 3, "title": "v2.0", "description": null, "state": "open", "due_on": null, "closed_issues": 0, "open_issues": 0}]"#.to_string()
1451    }
1452
1453    #[tokio::test]
1454    async fn test_should_wire_resolved_milestone_number_into_issue_create() {
1455        // Sequence: 1. milestone resolution: `gitcode milestone list -R owner/repo --json ...`
1456        //           2. `gitcode issue create ... --milestone 3`
1457        let runner = SequencedMockCommandRunner::from_results(&[
1458            (true, &milestone_list_fixture()),
1459            (
1460                true,
1461                r#"{"number":"42","title":"New feature","body":"Description","state":"open","labels":[],"user":{"login":"octocat","id":"1"},"assignees":[],"created_at":"2026-01-01T00:00:00Z","updated_at":"2026-01-01T00:00:00Z","html_url":"https://gitcode.com/owner/repo/issues/42","milestone":{"number":3,"title":"v2.0"}}"#,
1462            ),
1463        ]);
1464        let provider = GitCodeIssueProvider::with_runner("owner/repo", runner.clone());
1465
1466        let mut args = sample_create_args();
1467        args.milestone = Some("3".to_string()); // resolve by number
1468
1469        let issue = provider.create(args).await.expect("create should succeed");
1470
1471        assert_eq!(
1472            issue.milestone,
1473            Some(gitflow_core::types::MilestoneRef {
1474                number: 3,
1475                title: "v2.0".into()
1476            })
1477        );
1478
1479        let calls = runner.recorded_calls();
1480        assert_eq!(calls.len(), 2);
1481        assert_eq!(
1482            calls[0].1.first().map(String::as_str),
1483            Some("milestone"),
1484            "first call must resolve the milestone via `gitcode milestone list`, got: {:?}",
1485            calls[0].1
1486        );
1487        let create_call = &calls[1].1;
1488        assert!(
1489            create_call
1490                .windows(2)
1491                .any(|w| w[0] == "--milestone" && w[1] == "3"),
1492            "issue create argv must carry the resolved milestone NUMBER (not title), got: \
1493             {create_call:?}"
1494        );
1495    }
1496
1497    #[tokio::test]
1498    async fn test_should_propagate_error_when_milestone_identifier_not_found_on_issue_create() {
1499        let runner = MockCommandRunner::success("[]");
1500        let provider = GitCodeIssueProvider::with_runner("owner/repo", runner);
1501
1502        let mut args = sample_create_args();
1503        args.milestone = Some("does-not-exist".to_string());
1504
1505        let result = provider.create(args).await;
1506        assert!(result.is_err());
1507    }
1508
1509    #[tokio::test]
1510    async fn test_should_wire_resolved_milestone_number_into_issue_edit() {
1511        // Sequence: 1. milestone resolution
1512        //           2. `gitcode issue edit <number> --milestone 3`
1513        //           3. `gitcode issue view --json` (edit() re-fetches via view)
1514        let runner = SequencedMockCommandRunner::from_results(&[
1515            (true, &milestone_list_fixture()),
1516            (true, ""),
1517            (
1518                true,
1519                r#"{"number":"42","title":"T","body":null,"state":"open","labels":[],"user":{"login":"octocat","id":"1"},"assignees":[],"created_at":"2026-01-01T00:00:00Z","updated_at":"2026-01-01T00:00:00Z","html_url":"https://gitcode.com/owner/repo/issues/42","milestone":{"number":3,"title":"v2.0"}}"#,
1520            ),
1521        ]);
1522        let provider = GitCodeIssueProvider::with_runner("owner/repo", runner.clone());
1523
1524        let issue = provider
1525            .edit(
1526                42,
1527                gitflow_core::issue::EditIssueArgs {
1528                    title: None,
1529                    body: None,
1530                    milestone: Some(Some("3".to_string())),
1531                },
1532            )
1533            .await
1534            .expect("edit should succeed");
1535
1536        assert_eq!(issue.milestone.map(|m| m.number), Some(3));
1537
1538        let calls = runner.recorded_calls();
1539        let edit_call = &calls[1].1;
1540        assert!(
1541            edit_call
1542                .windows(2)
1543                .any(|w| w[0] == "--milestone" && w[1] == "3"),
1544            "issue edit argv must carry the resolved milestone NUMBER, got: {edit_call:?}"
1545        );
1546    }
1547
1548    #[tokio::test]
1549    async fn test_should_error_on_unassign_milestone_without_spawning_cli() {
1550        // Confirmed 2026-09-21 against byx-darwin/NexaTrade issue #1: neither
1551        // `--milestone 0` (rejected by the CLI's own flag parsing as "no edit
1552        // option provided") nor `--milestone -1` (silently ignored by the
1553        // backend — `issue view` right after still shows the original
1554        // milestone attached) actually unassigns. GitCode's CLI has no
1555        // unassign capability, so `Some(None)` must error before spawning
1556        // anything, not fake success.
1557        let runner = RecordingMockRunner::success("should not be called");
1558        let provider = GitCodeIssueProvider::with_runner("owner/repo", runner.clone());
1559
1560        let result = provider
1561            .edit(
1562                42,
1563                gitflow_core::issue::EditIssueArgs {
1564                    title: None,
1565                    body: None,
1566                    milestone: Some(None),
1567                },
1568            )
1569            .await;
1570
1571        let err = result.expect_err("unassign must error, not silently succeed");
1572        assert!(
1573            matches!(err, gitflow_core::CoreError::Platform(_)),
1574            "expected CoreError::Platform, got {err:?}"
1575        );
1576        assert!(
1577            runner.calls().is_empty(),
1578            "must reject before spawning the CLI, got calls: {:?}",
1579            runner.calls()
1580        );
1581    }
1582
1583    #[tokio::test]
1584    async fn test_should_wire_resolved_milestone_number_into_issue_list_filter() {
1585        // Sequence: 1. milestone resolution
1586        //           2. `gitcode issue list ... --milestone 3`
1587        let runner = SequencedMockCommandRunner::from_results(&[
1588            (true, &milestone_list_fixture()),
1589            (true, "[]"),
1590        ]);
1591        let provider = GitCodeIssueProvider::with_runner("owner/repo", runner.clone());
1592
1593        let _ = provider
1594            .list(ListIssueArgs {
1595                milestone: Some("v2.0".to_string()),
1596                ..ListIssueArgs::default()
1597            })
1598            .await;
1599
1600        let calls = runner.recorded_calls();
1601        let list_call = &calls[1].1;
1602        assert!(
1603            list_call
1604                .windows(2)
1605                .any(|w| w[0] == "--milestone" && w[1] == "3"),
1606            "issue list argv must carry the resolved milestone NUMBER (not title), got: \
1607             {list_call:?}"
1608        );
1609    }
1610
1611    // --- extract_missing_labels_from_error: pure-function tests ---
1612
1613    #[test]
1614    fn test_should_extract_single_missing_label_from_gc_stderr() {
1615        let stderr =
1616            b"failed to update https://gitcode.com/owner/repo/issues/18: 'type:enhancement' not found";
1617        let missing = extract_missing_labels_from_error(stderr);
1618        assert_eq!(missing, vec!["type:enhancement".to_string()]);
1619    }
1620
1621    #[test]
1622    fn test_should_return_empty_when_no_label_not_found_in_gc_stderr() {
1623        let stderr = b"gitcode: Not logged in";
1624        let missing = extract_missing_labels_from_error(stderr);
1625        assert!(missing.is_empty());
1626    }
1627
1628    // --- add_labels: auto-create missing labels ---
1629
1630    #[tokio::test]
1631    async fn test_should_auto_create_label_and_retry_on_add_labels() {
1632        // Sequence:
1633        // 1. `gc issue edit 18 --add-label type:enhancement` → fails
1634        // 2. `gc label create type:enhancement --color ededed -R owner/repo` → succeeds
1635        // 3. `gc issue edit 18 --add-label type:enhancement` → succeeds (retry)
1636        let runner = SequencedMockCommandRunner::from_results(&[
1637            (
1638                false,
1639                "failed to update https://gitcode.com/owner/repo/issues/18: 'type:enhancement' \
1640                 not found",
1641            ),
1642            (true, ""),
1643            (true, ""),
1644        ]);
1645        let provider = GitCodeIssueProvider::with_runner("owner/repo", runner);
1646
1647        let result = provider
1648            .add_labels(18, &["type:enhancement".to_string()])
1649            .await;
1650
1651        assert!(result.is_ok(), "expected Ok, got {result:?}");
1652    }
1653
1654    #[tokio::test]
1655    async fn test_should_propagate_error_when_gc_label_create_fails() {
1656        let runner = SequencedMockCommandRunner::from_results(&[
1657            (false, "failed to update ...: 'ghost' not found"),
1658            (false, "gitcode: 403 Forbidden"),
1659        ]);
1660        let provider = GitCodeIssueProvider::with_runner("o/r", runner);
1661
1662        let result = provider.add_labels(1, &["ghost".to_string()]).await;
1663
1664        assert!(result.is_err());
1665    }
1666
1667    #[tokio::test]
1668    async fn test_should_not_retry_on_non_label_error_gc() {
1669        let runner = SequencedMockCommandRunner::from_results(&[(false, "gitcode: Not logged in")]);
1670        let provider = GitCodeIssueProvider::with_runner("o/r", runner);
1671
1672        let result = provider.add_labels(1, &["bug".to_string()]).await;
1673
1674        assert!(result.is_err());
1675    }
1676
1677    #[tokio::test]
1678    async fn test_should_invoke_issue_label_subcommand_for_add_labels() {
1679        let runner = RecordingMockRunner::success("");
1680        let provider = GitCodeIssueProvider::with_runner("o/r", runner.clone());
1681
1682        provider
1683            .add_labels(54, &["type:bug".to_string(), "priority:high".to_string()])
1684            .await
1685            .expect("add_labels should succeed");
1686
1687        let calls = runner.calls();
1688        assert_eq!(calls.len(), 1);
1689        assert_eq!(
1690            calls[0],
1691            vec![
1692                "issue",
1693                "label",
1694                "54",
1695                "--add",
1696                "type:bug,priority:high",
1697                "-R",
1698                "o/r"
1699            ],
1700            r"gitcode v0.6.1 的 issue edit 没有 --add-label flag(Issue #90)"
1701        );
1702    }
1703
1704    #[tokio::test]
1705    async fn test_should_return_ok_without_any_call_for_empty_labels() {
1706        let runner = RecordingMockRunner::success("");
1707        let provider = GitCodeIssueProvider::with_runner("o/r", runner.clone());
1708
1709        provider
1710            .add_labels(1, &[])
1711            .await
1712            .expect("empty labels is a no-op");
1713
1714        assert!(runner.calls().is_empty());
1715    }
1716
1717    #[tokio::test]
1718    async fn test_should_invoke_issue_label_subcommand_for_remove_label() {
1719        let runner = RecordingMockRunner::success("");
1720        let provider = GitCodeIssueProvider::with_runner("o/r", runner.clone());
1721
1722        provider
1723            .remove_label(54, "triage:done")
1724            .await
1725            .expect("remove should succeed");
1726
1727        assert_eq!(
1728            runner.calls()[0],
1729            vec![
1730                "issue",
1731                "label",
1732                "54",
1733                "--remove",
1734                "triage:done",
1735                "-R",
1736                "o/r"
1737            ]
1738        );
1739    }
1740
1741    #[tokio::test]
1742    async fn test_should_auto_create_missing_label_and_retry_via_issue_label() {
1743        // 1. issue label --add 失败,报告标签缺失
1744        // 2. label create 成功(自动创建)
1745        // 3. issue label --add 重试成功
1746        let runner = SequencedMockCommandRunner::from_results(&[
1747            (false, "HTTP 404: 'type:new' not found"),
1748            (true, r#"{"name": "type:new", "color": "ededed"}"#),
1749            (true, ""),
1750        ]);
1751        let provider = GitCodeIssueProvider::with_runner("o/r", runner);
1752
1753        provider
1754            .add_labels(18, &["type:new".to_string()])
1755            .await
1756            .expect("should recover by auto-creating the label");
1757    }
1758
1759    #[test]
1760    fn test_should_parse_issue_comment_with_user_object() {
1761        let json = r#"{"id": 12, "body": "hi", "user": {"login": "bob", "id": "u2"}, "created_at": "2026-07-30T12:00:00+08:00"}"#;
1762        let api: CommentApiResponse = serde_json::from_str(json).expect("user-object shape");
1763        let comment: CommentData = api.into();
1764        assert_eq!(comment.id, 12);
1765        assert_eq!(comment.author.login, "bob");
1766        assert_eq!(comment.author.id, "u2");
1767    }
1768
1769    /// 构造 `count` 条合法 issue JSON,编号从 `start` 递增。
1770    fn issue_page_json(start: u64, count: u64) -> String {
1771        let items: Vec<String> = (start..start + count)
1772            .map(|n| {
1773                format!(
1774                    r#"{{"number":"{n}","title":"t{n}","state":"open","body":null,"labels":[],"created_at":"2026-07-30T12:00:00+08:00","updated_at":"2026-07-30T12:00:00+08:00","html_url":"https://gitcode.com/owner/repo/issues/{n}"}}"#
1775                )
1776            })
1777            .collect();
1778        format!("[{}]", items.join(","))
1779    }
1780
1781    #[tokio::test]
1782    async fn test_should_page_through_gitcode_issue_list_with_incrementing_page_numbers() {
1783        // cap=100 → per_page=min(101,100)=100,want=cap+1=101。
1784        // 首页满 100 条:既非短页,又未达 want ⇒ `fetch_capped` 必然发出第二页。
1785        // 这是唯一能观测到页号递增的取值区间 —— cap < 100 时 per_page 恰为
1786        // cap+1,首页一次就满足 want,循环只会发出一次调用。
1787        let page1 = issue_page_json(1, 100);
1788        let page2 = issue_page_json(101, 100);
1789        let runner = SequencedMockCommandRunner::from_results(&[(true, &page1), (true, &page2)]);
1790        let provider = GitCodeIssueProvider::with_runner("owner/repo", runner.clone());
1791
1792        let result = provider
1793            .list(ListIssueArgs {
1794                limit: Some(100),
1795                ..ListIssueArgs::default()
1796            })
1797            .await
1798            .expect("list should succeed");
1799
1800        assert_eq!(result.items.len(), 100, "返回条数必须被 cap 钳住");
1801        assert!(result.truncated, "超过 cap 必须诚实报告截断");
1802
1803        let calls = runner.recorded_calls();
1804        assert_eq!(
1805            calls.len(),
1806            2,
1807            "必须真的翻到第二页,实际调用数: {}",
1808            calls.len()
1809        );
1810        let first = &calls[0].1;
1811        assert!(
1812            first
1813                .windows(2)
1814                .any(|w| w[0] == "--per-page" && w[1] == "100"),
1815            "首次调用必须显式传 --per-page,实际 argv: {first:?}"
1816        );
1817        assert!(
1818            first.windows(2).any(|w| w[0] == "--page" && w[1] == "1"),
1819            "首次调用必须显式传 --page=1,实际 argv: {first:?}"
1820        );
1821        assert!(
1822            !first.iter().any(|a| a == "--limit"),
1823            "--per-page 已决定单页大小,不得再传 --limit,实际 argv: {first:?}"
1824        );
1825        let second = &calls[1].1;
1826        assert!(
1827            second.windows(2).any(|w| w[0] == "--page" && w[1] == "2"),
1828            "页号必须在翻页中递增,实际 argv: {second:?}"
1829        );
1830    }
1831
1832    #[tokio::test]
1833    async fn test_should_report_no_truncation_when_gitcode_issue_list_ends_on_short_page() {
1834        // cap=150 → per_page=min(151,100)=100,want=cap+1=151。
1835        // 首页满 100 条(非短页,且未达 want)⇒ 循环必须继续翻到第二页;
1836        // 第二页返回 20 条(短页)⇒ 循环必须就此停止,不再探第三页。
1837        // 总条目 120 < cap=150,因此必须诚实报告 truncated=false。
1838        let page1 = issue_page_json(1, 100);
1839        let page2 = issue_page_json(101, 20);
1840        let runner = SequencedMockCommandRunner::from_results(&[(true, &page1), (true, &page2)]);
1841        let provider = GitCodeIssueProvider::with_runner("owner/repo", runner.clone());
1842
1843        let result = provider
1844            .list(ListIssueArgs {
1845                limit: Some(150),
1846                ..ListIssueArgs::default()
1847            })
1848            .await
1849            .expect("list should succeed");
1850
1851        assert_eq!(result.items.len(), 120, "两页条目必须全部保留,不得丢数据");
1852        assert!(!result.truncated, "总数未达 cap,必须诚实报告未截断");
1853
1854        let calls = runner.recorded_calls();
1855        assert_eq!(
1856            calls.len(),
1857            2,
1858            "短页应在第二页停止,不得再探第三页,实际调用数: {}",
1859            calls.len()
1860        );
1861        let first = &calls[0].1;
1862        assert!(
1863            first.windows(2).any(|w| w[0] == "--page" && w[1] == "1"),
1864            "首次调用必须显式传 --page=1,实际 argv: {first:?}"
1865        );
1866        let second = &calls[1].1;
1867        assert!(
1868            second.windows(2).any(|w| w[0] == "--page" && w[1] == "2"),
1869            "第二次调用必须显式传 --page=2,实际 argv: {second:?}"
1870        );
1871    }
1872
1873    #[tokio::test]
1874    async fn test_should_cap_gitcode_issue_per_page_at_api_maximum() {
1875        let runner = MockCommandRunner::success("[]");
1876        let provider = GitCodeIssueProvider::with_runner("owner/repo", runner.clone());
1877
1878        provider
1879            .list(ListIssueArgs::default())
1880            .await
1881            .expect("list should succeed");
1882
1883        let recorded = &runner.recorded_calls()[0].1;
1884        assert!(
1885            recorded
1886                .windows(2)
1887                .any(|w| w[0] == "--per-page" && w[1] == "100"),
1888            "默认 cap=1000 时 per_page 必须被 API 上限 100 钳住,实际 argv: {recorded:?}"
1889        );
1890    }
1891
1892    #[tokio::test]
1893    async fn test_should_keep_forwarding_label_filter_on_gitcode() {
1894        let runner = MockCommandRunner::success("[]");
1895        let provider = GitCodeIssueProvider::with_runner("owner/repo", runner.clone());
1896        let args = ListIssueArgs {
1897            labels: vec!["bug".to_string()],
1898            ..ListIssueArgs::default()
1899        };
1900        provider.list(args).await.expect("list should succeed");
1901        let recorded = &runner.recorded_calls()[0].1;
1902        assert!(
1903            recorded
1904                .windows(2)
1905                .any(|w| w[0] == "--label" && w[1] == "bug")
1906        );
1907    }
1908
1909    #[tokio::test]
1910    async fn test_should_list_issues_with_state_and_label_using_full_argv() {
1911        let runner = MockCommandRunner::success("[]");
1912        let provider = GitCodeIssueProvider::with_runner("owner/repo", runner.clone());
1913
1914        let _ = provider
1915            .list(ListIssueArgs {
1916                state: Some(State::Open),
1917                labels: vec!["bug".to_string()],
1918                ..ListIssueArgs::default()
1919            })
1920            .await;
1921
1922        assert_eq!(
1923            runner.recorded_calls()[0].1,
1924            vec![
1925                "issue",
1926                "list",
1927                "-R",
1928                "owner/repo",
1929                "--json",
1930                "--state",
1931                "open",
1932                "--label",
1933                "bug",
1934                "--per-page",
1935                "100",
1936                "--page",
1937                "1"
1938            ]
1939            .into_iter()
1940            .map(String::from)
1941            .collect::<Vec<_>>()
1942        );
1943    }
1944}
1945
1946#[cfg(test)]
1947mod contract_tests {
1948    use super::*;
1949    use crate::runner::MockCommandRunner;
1950
1951    /// 契约测试:验证 gitcode issue list JSON 输出与反序列化一致。
1952    ///
1953    /// 夹具来源:gitcode v0.6.x 真实 CLI 输出。
1954    #[tokio::test]
1955    async fn test_contract_issue_list_gitcode_v0_6() {
1956        let fixture = include_str!("../tests/fixtures/issue_list_gitcode_v0.6.json");
1957        let runner = MockCommandRunner::success(fixture);
1958        let provider = GitCodeIssueProvider::with_runner("owner/repo", runner);
1959
1960        let issues = provider
1961            .list(ListIssueArgs::default())
1962            .await
1963            .expect("contract fixture must parse");
1964        let issues = issues.items;
1965
1966        assert_eq!(issues.len(), 1);
1967        let issue = &issues[0];
1968        assert_eq!(issue.number, 15);
1969        assert!(!issue.title.is_empty());
1970        assert_eq!(issue.state, gitflow_core::types::State::Open);
1971    }
1972}