Skip to main content

gitflow_github/
label.rs

1//! GitHub Label 和 Milestone 提供者实现。
2//!
3//! 通过 `gh label` 和 `gh api` CLI 命令实现 [`LabelProvider`] 和
4//! [`MilestoneProvider`] trait,支持标签和里程碑的完整生命周期管理。
5
6use async_trait::async_trait;
7use chrono::{DateTime, Utc};
8use gitflow_core::{
9    CoreError, DEFAULT_LIST_LIMIT, FetchStrategy, Paged, Result, fetch_capped,
10    label::{
11        CreateLabelArgs, CreateMilestoneArgs, LabelData, LabelProvider, MilestoneData,
12        MilestoneProvider,
13    },
14    types::State,
15};
16use serde::Deserialize;
17use tracing::debug;
18
19use crate::{
20    GITHUB_API_MAX_PER_PAGE,
21    error::parse_gh_error,
22    runner::{CommandRunner, RealCommandRunner},
23};
24
25/// GitHub Label 提供者,通过 `gh` CLI 管理仓库标签。
26///
27/// # Examples
28///
29/// ```no_run
30/// use gitflow_github::GitHubLabelProvider;
31///
32/// let provider = GitHubLabelProvider::new("octocat/hello-world");
33/// ```
34#[derive(Debug, Clone)]
35pub struct GitHubLabelProvider<R: CommandRunner = RealCommandRunner> {
36    /// GitHub `owner/repo`。
37    repo: String,
38    /// 用于执行 `gh` CLI 命令的 runner。
39    runner: R,
40}
41
42impl GitHubLabelProvider<RealCommandRunner> {
43    /// 创建新的 GitHub Label 提供者。
44    ///
45    /// `repo` 格式为 `owner/repo`。
46    #[must_use]
47    pub fn new(repo: impl Into<String>) -> Self {
48        Self {
49            repo: repo.into(),
50            runner: RealCommandRunner,
51        }
52    }
53
54    /// Create a new provider from a shared [`Session`].
55    ///
56    /// This enables state reuse across multiple operations in workflow chains.
57    #[must_use]
58    pub fn with_session(session: &gitflow_core::Session) -> Self {
59        Self {
60            repo: session.repo.clone(),
61            runner: RealCommandRunner,
62        }
63    }
64}
65
66impl<R: CommandRunner> GitHubLabelProvider<R> {
67    /// 使用自定义 [`CommandRunner`] 创建提供者。
68    ///
69    /// 主要用于测试,可注入模拟 runner 以控制 `gh` CLI 的输出。
70    /// `repo` 格式为 `owner/repo`。
71    #[must_use]
72    pub fn with_runner(repo: impl Into<String>, runner: R) -> Self {
73        Self {
74            repo: repo.into(),
75            runner,
76        }
77    }
78}
79
80/// `gh label list/create` 请求的 JSON 字段列表。
81const LABEL_FIELDS: &str = "name,color,description";
82
83#[async_trait]
84impl<R: CommandRunner + 'static> LabelProvider for GitHubLabelProvider<R> {
85    async fn create(&self, args: CreateLabelArgs) -> Result<LabelData> {
86        debug!(
87            repo = %self.repo,
88            name = %args.name,
89            color = %args.color,
90            "spawning `gh label create`"
91        );
92
93        let mut cmd_args: Vec<&str> = vec![
94            "label",
95            "create",
96            &args.name,
97            "--color",
98            &args.color,
99            "--repo",
100            &self.repo,
101        ];
102
103        if let Some(ref desc) = args.description {
104            cmd_args.push("--description");
105            cmd_args.push(desc);
106        }
107
108        let output =
109            self.runner.run("gh", &cmd_args).await.map_err(|e| {
110                CoreError::Platform(format!("Failed to spawn gh label create: {e}"))
111            })?;
112
113        if !output.status.success() {
114            return Err(parse_gh_error(&output.stderr).into());
115        }
116
117        // gh label create doesn't return JSON, construct the response manually
118        Ok(LabelData {
119            name: args.name,
120            color: Some(args.color),
121            description: args.description,
122        })
123    }
124
125    async fn list(&self, limit: Option<u32>) -> Result<Paged<LabelData>> {
126        let cap = limit.unwrap_or(DEFAULT_LIST_LIMIT);
127        let repo = &self.repo;
128        let runner = &self.runner;
129
130        debug!(repo = %self.repo, cap, "spawning `gh label list`");
131
132        fetch_capped(FetchStrategy::SingleShot, cap, |_page, want| async move {
133            let want_str = want.to_string();
134            let output = runner
135                .run(
136                    "gh",
137                    &[
138                        "label",
139                        "list",
140                        "--repo",
141                        repo,
142                        "--json",
143                        LABEL_FIELDS,
144                        "--limit",
145                        &want_str,
146                    ],
147                )
148                .await
149                .map_err(|e| CoreError::Platform(format!("Failed to spawn gh label list: {e}")))?;
150
151            if !output.status.success() {
152                return Err(parse_gh_error(&output.stderr).into());
153            }
154
155            let labels: Vec<LabelData> =
156                serde_json::from_slice(&output.stdout).map_err(CoreError::Serialization)?;
157            Ok(labels)
158        })
159        .await
160    }
161
162    async fn edit(&self, name: &str, args: CreateLabelArgs) -> Result<LabelData> {
163        debug!(repo = %self.repo, name, "spawning `gh label edit`");
164
165        let mut cmd_args: Vec<&str> = vec![
166            "label",
167            "edit",
168            name,
169            "--repo",
170            &self.repo,
171            "--color",
172            &args.color,
173        ];
174
175        if let Some(ref desc) = args.description {
176            cmd_args.push("--description");
177            cmd_args.push(desc);
178        }
179
180        let output = self
181            .runner
182            .run("gh", &cmd_args)
183            .await
184            .map_err(|e| CoreError::Platform(format!("Failed to spawn gh label edit: {e}")))?;
185
186        if !output.status.success() {
187            return Err(parse_gh_error(&output.stderr).into());
188        }
189
190        // gh label edit 不返回 JSON,重新 fetch 获取最新数据
191        self.fetch_label(name).await
192    }
193
194    async fn delete(&self, name: &str) -> Result<()> {
195        debug!(repo = %self.repo, name, "spawning `gh label delete`");
196
197        let output = self
198            .runner
199            .run(
200                "gh",
201                &["label", "delete", name, "--yes", "--repo", &self.repo],
202            )
203            .await
204            .map_err(|e| CoreError::Platform(format!("Failed to spawn gh label delete: {e}")))?;
205
206        if !output.status.success() {
207            return Err(parse_gh_error(&output.stderr).into());
208        }
209
210        Ok(())
211    }
212}
213
214impl<R: CommandRunner> GitHubLabelProvider<R> {
215    /// 获取指定名称的标签数据(内部辅助方法)。
216    ///
217    /// 调用 `gh api` REST 端点 `repos/{owner}/{repo}/labels/{name}` 重新拉取。
218    /// gh 2.97 没有 `label view` 子命令,故不能用 `gh label view --json`。
219    async fn fetch_label(&self, name: &str) -> Result<LabelData> {
220        let api_path = format!(
221            "repos/{repo}/labels/{name}",
222            repo = self.repo,
223            name = encode_path_segment(name)
224        );
225
226        let output = self
227            .runner
228            .run("gh", &["api", &api_path])
229            .await
230            .map_err(|e| CoreError::Platform(format!("Failed to spawn gh api label: {e}")))?;
231
232        if !output.status.success() {
233            return Err(parse_gh_error(&output.stderr).into());
234        }
235
236        let label: LabelData =
237            serde_json::from_slice(&output.stdout).map_err(CoreError::Serialization)?;
238
239        Ok(label)
240    }
241}
242
243/// RFC 3986 路径段编码:仅保留 unreserved 字符,其余按字节百分号编码(大写十六进制)。
244///
245/// 用于在 `gh api repos/{owner}/{repo}/labels/{name}` 路径中编码标签名,
246/// 标签名可能包含空格或特殊字符(如 `good first issue`)。
247#[must_use]
248fn encode_path_segment(value: &str) -> String {
249    const HEX_DIGITS: &[u8; 16] = b"0123456789ABCDEF";
250    let mut out = String::with_capacity(value.len());
251    for b in value.bytes() {
252        match b {
253            b'A'..=b'Z' | b'a'..=b'z' | b'0'..=b'9' | b'-' | b'.' | b'_' | b'~' => {
254                out.push(char::from(b));
255            }
256            _ => {
257                out.push('%');
258                out.push(char::from(HEX_DIGITS[usize::from(b >> 4)]));
259                out.push(char::from(HEX_DIGITS[usize::from(b & 0x0F)]));
260            }
261        }
262    }
263    out
264}
265
266/// GitHub 里程碑提供者,通过 `gh api` 管理仓库里程碑。
267///
268/// # Examples
269///
270/// ```no_run
271/// use gitflow_github::GitHubMilestoneProvider;
272///
273/// let provider = GitHubMilestoneProvider::new("octocat/hello-world");
274/// ```
275#[derive(Debug, Clone)]
276pub struct GitHubMilestoneProvider<R: CommandRunner = RealCommandRunner> {
277    /// GitHub `owner/repo`。
278    repo: String,
279    /// 用于执行 `gh` CLI 命令的 runner。
280    runner: R,
281}
282
283impl GitHubMilestoneProvider<RealCommandRunner> {
284    /// 创建新的 GitHub Milestone 提供者。
285    ///
286    /// `repo` 格式为 `owner/repo`。
287    #[must_use]
288    pub fn new(repo: impl Into<String>) -> Self {
289        Self {
290            repo: repo.into(),
291            runner: RealCommandRunner,
292        }
293    }
294
295    /// Create a new provider from a shared [`Session`].
296    ///
297    /// This enables state reuse across multiple operations in workflow chains.
298    #[must_use]
299    pub fn with_session(session: &gitflow_core::Session) -> Self {
300        Self {
301            repo: session.repo.clone(),
302            runner: RealCommandRunner,
303        }
304    }
305}
306
307impl<R: CommandRunner> GitHubMilestoneProvider<R> {
308    /// 使用自定义 [`CommandRunner`] 创建提供者。
309    ///
310    /// 主要用于测试,可注入模拟 runner 以控制 `gh` CLI 的输出。
311    /// `repo` 格式为 `owner/repo`。
312    #[must_use]
313    pub fn with_runner(repo: impl Into<String>, runner: R) -> Self {
314        Self {
315            repo: repo.into(),
316            runner,
317        }
318    }
319}
320
321/// `gh api milestones` 返回的 JSON 结构。
322#[derive(Debug, Clone, Deserialize)]
323struct MilestoneApiResponse {
324    number: u64,
325    title: String,
326    #[serde(default)]
327    description: Option<String>,
328    state: String,
329    #[serde(default)]
330    due_on: Option<String>,
331    #[serde(default)]
332    closed_issues: u64,
333    #[serde(default)]
334    open_issues: u64,
335}
336
337impl From<MilestoneApiResponse> for MilestoneData {
338    fn from(api: MilestoneApiResponse) -> Self {
339        Self {
340            number: api.number,
341            title: api.title,
342            description: api.description,
343            state: if api.state == "closed" {
344                State::Closed
345            } else {
346                State::Open
347            },
348            due_on: api.due_on.and_then(|s| {
349                DateTime::parse_from_rfc3339(&s).map_or(None, |dt| Some(dt.with_timezone(&Utc)))
350            }),
351            closed_issues: api.closed_issues,
352            open_issues: api.open_issues,
353        }
354    }
355}
356
357#[async_trait]
358impl<R: CommandRunner + 'static> MilestoneProvider for GitHubMilestoneProvider<R> {
359    async fn create(&self, args: CreateMilestoneArgs) -> Result<MilestoneData> {
360        debug!(repo = %self.repo, title = %args.title, "spawning `gh api milestones POST`");
361
362        let api_path = format!("repos/{repo}/milestones", repo = self.repo);
363
364        let mut cmd = tokio::process::Command::new("gh");
365        cmd.args(["api", &api_path, "-X", "POST"])
366            .arg("-f")
367            .arg(format!("title={}", args.title));
368
369        if let Some(ref desc) = args.description {
370            cmd.arg("-f").arg(format!("description={desc}"));
371        }
372
373        if let Some(ref due) = args.due_on {
374            cmd.arg("-f").arg(format!("due_on={}", due.to_rfc3339()));
375        }
376
377        let output = cmd
378            .output()
379            .await
380            .map_err(|e| CoreError::Platform(format!("Failed to spawn gh api milestones: {e}")))?;
381
382        if !output.status.success() {
383            return Err(parse_gh_error(&output.stderr).into());
384        }
385
386        let api_response: MilestoneApiResponse =
387            serde_json::from_slice(&output.stdout).map_err(CoreError::Serialization)?;
388
389        Ok(api_response.into())
390    }
391
392    async fn list(&self, limit: Option<u32>) -> Result<Paged<MilestoneData>> {
393        let cap = limit.unwrap_or(DEFAULT_LIST_LIMIT);
394        let repo = &self.repo;
395        let runner = &self.runner;
396
397        debug!(repo = %self.repo, cap, "spawning `gh api` GET milestones");
398
399        fetch_capped(
400            FetchStrategy::Paged {
401                per_page: cap.saturating_add(1).min(GITHUB_API_MAX_PER_PAGE),
402            },
403            cap,
404            |page, per_page| async move {
405                // gh api 直接接受 per_page / page 查询参数(已实测),
406                // 因此无需 --paginate,且截断可被探测。
407                let api_path = format!("repos/{repo}/milestones?per_page={per_page}&page={page}");
408
409                let output = runner.run("gh", &["api", &api_path]).await.map_err(|e| {
410                    CoreError::Platform(format!("Failed to spawn gh api milestones: {e}"))
411                })?;
412
413                if !output.status.success() {
414                    return Err(parse_gh_error(&output.stderr).into());
415                }
416
417                let milestones: Vec<MilestoneApiResponse> =
418                    serde_json::from_slice(&output.stdout).map_err(CoreError::Serialization)?;
419                Ok(milestones.into_iter().map(MilestoneData::from).collect())
420            },
421        )
422        .await
423    }
424
425    async fn edit(&self, number: u64, args: CreateMilestoneArgs) -> Result<MilestoneData> {
426        debug!(repo = %self.repo, number, "spawning `gh api milestones PATCH`");
427
428        let api_path = format!("repos/{repo}/milestones/{number}", repo = self.repo);
429
430        let mut cmd = tokio::process::Command::new("gh");
431        cmd.args(["api", &api_path, "-X", "PATCH"]);
432
433        cmd.arg("-f").arg(format!("title={}", args.title));
434
435        if let Some(ref desc) = args.description {
436            cmd.arg("-f").arg(format!("description={desc}"));
437        }
438
439        if let Some(ref due) = args.due_on {
440            cmd.arg("-f").arg(format!("due_on={}", due.to_rfc3339()));
441        }
442
443        let output = cmd.output().await.map_err(|e| {
444            CoreError::Platform(format!("Failed to spawn gh api milestone edit: {e}"))
445        })?;
446
447        if !output.status.success() {
448            return Err(parse_gh_error(&output.stderr).into());
449        }
450
451        let api_response: MilestoneApiResponse =
452            serde_json::from_slice(&output.stdout).map_err(CoreError::Serialization)?;
453
454        Ok(api_response.into())
455    }
456
457    async fn close(&self, number: u64) -> Result<MilestoneData> {
458        debug!(repo = %self.repo, number, "spawning `gh api milestones close`");
459
460        let api_path = format!("repos/{repo}/milestones/{number}", repo = self.repo);
461
462        let output = tokio::process::Command::new("gh")
463            .args(["api", &api_path, "-X", "PATCH", "-f", "state=closed"])
464            .output()
465            .await
466            .map_err(|e| {
467                CoreError::Platform(format!("Failed to spawn gh api milestone close: {e}"))
468            })?;
469
470        if !output.status.success() {
471            return Err(parse_gh_error(&output.stderr).into());
472        }
473
474        let api_response: MilestoneApiResponse =
475            serde_json::from_slice(&output.stdout).map_err(CoreError::Serialization)?;
476
477        Ok(api_response.into())
478    }
479
480    async fn reopen(&self, number: u64) -> Result<MilestoneData> {
481        debug!(repo = %self.repo, number, "spawning `gh api milestones reopen`");
482
483        let api_path = format!("repos/{repo}/milestones/{number}", repo = self.repo);
484
485        let output = tokio::process::Command::new("gh")
486            .args(["api", &api_path, "-X", "PATCH", "-f", "state=open"])
487            .output()
488            .await
489            .map_err(|e| {
490                CoreError::Platform(format!("Failed to spawn gh api milestone reopen: {e}"))
491            })?;
492
493        if !output.status.success() {
494            return Err(parse_gh_error(&output.stderr).into());
495        }
496
497        let api_response: MilestoneApiResponse =
498            serde_json::from_slice(&output.stdout).map_err(CoreError::Serialization)?;
499
500        Ok(api_response.into())
501    }
502}
503
504#[cfg(test)]
505mod tests {
506    use super::*;
507    use crate::runner::{MockCommandRunner, SequencedMockCommandRunner};
508
509    // --- GitHubLabelProvider tests ---
510
511    #[test]
512    fn test_should_construct_github_label_provider() {
513        let provider = GitHubLabelProvider::new("octocat/hello-world");
514        assert_eq!(provider.repo, "octocat/hello-world");
515    }
516
517    #[test]
518    fn test_should_construct_github_label_provider_from_string() {
519        let repo = String::from("octocat/hello-world");
520        let provider = GitHubLabelProvider::new(repo);
521        assert_eq!(provider.repo, "octocat/hello-world");
522    }
523
524    #[test]
525    fn test_should_debug_format_label_provider() {
526        let provider = GitHubLabelProvider::new("owner/repo");
527        let debug = format!("{provider:?}");
528        assert!(debug.contains("GitHubLabelProvider"));
529        assert!(debug.contains("owner/repo"));
530    }
531
532    #[test]
533    fn test_should_clone_github_label_provider() {
534        let original = GitHubLabelProvider::new("owner/repo");
535        let cloned = original.clone();
536        assert_eq!(original.repo, cloned.repo);
537    }
538
539    #[tokio::test]
540    async fn test_should_fetch_label_via_gh_api() {
541        let runner = MockCommandRunner::success(
542            r#"{"name":"bug","color":"d73a4a","description":"Something isn't working"}"#,
543        );
544        let provider = GitHubLabelProvider::with_runner("octocat/hello-world", runner.clone());
545
546        let label = provider.fetch_label("bug").await.expect("should fetch");
547
548        assert_eq!(label.name, "bug");
549        assert_eq!(label.color.as_deref(), Some("d73a4a"));
550        assert_eq!(
551            runner.recorded_calls()[0].1,
552            vec!["api", "repos/octocat/hello-world/labels/bug"]
553        );
554    }
555
556    #[tokio::test]
557    async fn test_should_encode_label_name_in_api_path() {
558        let runner = MockCommandRunner::success(r#"{"name":"good first issue","color":"7057ff"}"#);
559        let provider = GitHubLabelProvider::with_runner("octocat/hello-world", runner.clone());
560
561        let label = provider
562            .fetch_label("good first issue")
563            .await
564            .expect("should fetch");
565
566        assert_eq!(label.name, "good first issue");
567        assert_eq!(
568            runner.recorded_calls()[0].1,
569            vec![
570                "api",
571                "repos/octocat/hello-world/labels/good%20first%20issue"
572            ]
573        );
574    }
575
576    #[tokio::test]
577    async fn test_should_edit_label_and_refetch_via_gh_api() {
578        let runner =
579            MockCommandRunner::success(r#"{"name":"bug","color":"3344ff","description":"probe2"}"#);
580        let provider = GitHubLabelProvider::with_runner("byx-darwin/gitflow-cli", runner.clone());
581
582        let args = CreateLabelArgs {
583            name: "bug".to_string(),
584            color: "3344ff".to_string(),
585            description: Some("probe2".to_string()),
586        };
587        let label = provider.edit("bug", args).await.expect("should edit");
588
589        assert_eq!(label.color.as_deref(), Some("3344ff"));
590        let calls = runner.recorded_calls();
591        assert_eq!(calls.len(), 2);
592        assert_eq!(
593            calls[0].1,
594            vec![
595                "label",
596                "edit",
597                "bug",
598                "--repo",
599                "byx-darwin/gitflow-cli",
600                "--color",
601                "3344ff",
602                "--description",
603                "probe2"
604            ]
605        );
606        // P1 regression: second call must be `gh api`, NEVER `gh label view`.
607        assert_eq!(
608            calls[1].1,
609            vec!["api", "repos/byx-darwin/gitflow-cli/labels/bug"]
610        );
611        assert!(
612            calls
613                .iter()
614                .all(|(_, args)| args.first().is_some_and(|a| a != "view")),
615            "no `gh label view` call may remain"
616        );
617    }
618
619    #[tokio::test]
620    async fn test_should_fail_when_fetch_label_api_fails() {
621        let runner = MockCommandRunner::failure("HTTP 404", 1);
622        let provider = GitHubLabelProvider::with_runner("owner/repo", runner);
623
624        let err = provider
625            .fetch_label("missing")
626            .await
627            .expect_err("should fail");
628        assert!(err.to_string().contains("GitHub") || err.to_string().contains("执行失败"));
629    }
630
631    #[tokio::test]
632    async fn test_should_list_labels_with_limit_flag() {
633        let runner = MockCommandRunner::success("[]");
634        let provider = GitHubLabelProvider::with_runner("owner/repo", runner.clone());
635
636        let paged = provider.list(None).await.expect("should list");
637
638        assert!(paged.items.is_empty());
639        assert_eq!(runner.recorded_calls()[0].0, "gh");
640        assert_eq!(
641            runner.recorded_calls()[0].1,
642            vec![
643                "label",
644                "list",
645                "--repo",
646                "owner/repo",
647                "--json",
648                "name,color,description",
649                "--limit",
650                "1001"
651            ]
652        );
653    }
654
655    #[tokio::test]
656    async fn test_should_create_label_via_runner() {
657        let runner = MockCommandRunner::success("");
658        let provider = GitHubLabelProvider::with_runner("owner/repo", runner.clone());
659
660        let args = CreateLabelArgs {
661            name: "bug".to_string(),
662            color: "d73a4a".to_string(),
663            description: None,
664        };
665        let label = provider.create(args).await.expect("should create");
666
667        assert_eq!(label.name, "bug");
668        assert_eq!(label.color.as_deref(), Some("d73a4a"));
669        assert_eq!(
670            runner.recorded_calls()[0].1,
671            vec![
672                "label",
673                "create",
674                "bug",
675                "--color",
676                "d73a4a",
677                "--repo",
678                "owner/repo"
679            ]
680        );
681    }
682
683    #[tokio::test]
684    async fn test_should_delete_label_via_runner() {
685        let runner = MockCommandRunner::success("");
686        let provider = GitHubLabelProvider::with_runner("owner/repo", runner.clone());
687
688        provider.delete("bug").await.expect("should delete");
689
690        assert_eq!(
691            runner.recorded_calls()[0].1,
692            vec!["label", "delete", "bug", "--yes", "--repo", "owner/repo"]
693        );
694    }
695
696    #[tokio::test]
697    async fn test_should_route_milestone_list_through_runner() {
698        let runner = MockCommandRunner::success("[]");
699        let provider = GitHubMilestoneProvider::with_runner("owner/repo", runner.clone());
700
701        let paged = provider.list(None).await.expect("should list");
702
703        assert!(paged.items.is_empty());
704        let calls = runner.recorded_calls();
705        assert_eq!(calls.len(), 1);
706        assert_eq!(calls[0].0, "gh");
707        assert_eq!(calls[0].1[0], "api");
708        assert!(calls[0].1[1].contains("per_page=100"));
709        assert!(calls[0].1[1].contains("page=1"));
710    }
711
712    #[tokio::test]
713    async fn test_should_produce_complete_argv_for_milestone_list_with_default_limit() {
714        let runner = MockCommandRunner::success("[]");
715        let provider = GitHubMilestoneProvider::with_runner("owner/repo", runner.clone());
716
717        let paged = provider.list(None).await.expect("should list");
718
719        assert!(paged.items.is_empty());
720        assert_eq!(
721            runner.recorded_calls()[0].1,
722            vec!["api", "repos/owner/repo/milestones?per_page=100&page=1"]
723        );
724    }
725
726    /// 证明分页确实会递增页码,而不仅仅是原语层面的假设。
727    ///
728    /// 之前所有 argv 测试都用 `MockCommandRunner::success("[]")`,空数组
729    /// 在第 1 页就短页,从未真正观察到 `page=2` 出现在 argv 里。这里用
730    /// `cap=150` 强制 `per_page` 封顶在 100(`GITHUB_API_MAX_PER_PAGE`),
731    /// 第一页给满 100 条(不短页、也不够 N+1 探测所需的 151 条),逼出
732    /// 第二页请求;第二页给 51 条(短页)以终止循环。
733    #[tokio::test]
734    async fn test_should_increment_page_across_calls_for_milestone_list() {
735        let full_page: Vec<String> = (0..100)
736            .map(|i| {
737                format!(
738                    r#"{{"number":{i},"title":"v{i}","state":"open","closed_issues":0,"open_issues":0}}"#
739                )
740            })
741            .collect();
742        let full_page_json = format!("[{}]", full_page.join(","));
743
744        let short_page: Vec<String> = (100..151)
745            .map(|i| {
746                format!(
747                    r#"{{"number":{i},"title":"v{i}","state":"open","closed_issues":0,"open_issues":0}}"#
748                )
749            })
750            .collect();
751        let short_page_json = format!("[{}]", short_page.join(","));
752
753        let runner = SequencedMockCommandRunner::from_results(&[
754            (true, &full_page_json),
755            (true, &short_page_json),
756        ]);
757        let provider = GitHubMilestoneProvider::with_runner("owner/repo", runner.clone());
758
759        let paged = provider
760            .list(Some(150))
761            .await
762            .expect("should list across two pages");
763
764        assert_eq!(paged.items.len(), 150);
765        assert!(
766            paged.truncated,
767            "100 + 51 = 151 条超出 cap=150,N+1 探测必须报告截断"
768        );
769
770        let calls = runner.recorded_calls();
771        assert_eq!(calls.len(), 2, "必须恰好翻两页");
772        assert_eq!(calls[0].0, "gh");
773        assert_eq!(calls[1].0, "gh");
774        assert!(
775            calls[0].1[1].contains("page=1"),
776            "第一次调用必须请求 page=1,实际: {:?}",
777            calls[0].1
778        );
779        assert!(
780            calls[1].1[1].contains("page=2"),
781            "第二次调用必须请求 page=2,实际: {:?}",
782            calls[1].1
783        );
784    }
785
786    // --- GitHubMilestoneProvider tests ---
787
788    #[test]
789    fn test_should_construct_github_milestone_provider() {
790        let provider = GitHubMilestoneProvider::new("octocat/hello-world");
791        assert_eq!(provider.repo, "octocat/hello-world");
792    }
793
794    #[test]
795    fn test_should_debug_format_milestone_provider() {
796        let provider = GitHubMilestoneProvider::new("owner/repo");
797        let debug = format!("{provider:?}");
798        assert!(debug.contains("GitHubMilestoneProvider"));
799        assert!(debug.contains("owner/repo"));
800    }
801
802    #[test]
803    fn test_should_clone_github_milestone_provider() {
804        let original = GitHubMilestoneProvider::new("owner/repo");
805        let cloned = original.clone();
806        assert_eq!(original.repo, cloned.repo);
807    }
808
809    // --- LabelData deserialization tests ---
810
811    #[test]
812    fn test_should_deserialize_label_data_from_gh_output() {
813        let json = br#"[
814            {"name": "bug", "color": "d73a4a", "description": "Something isn't working"},
815            {"name": "enhancement", "color": "a2eeef", "description": null}
816        ]"#;
817
818        let labels: Vec<LabelData> = serde_json::from_slice(json).expect("valid LabelData list");
819        assert_eq!(labels.len(), 2);
820        assert_eq!(labels[0].name, "bug");
821        assert_eq!(labels[0].color.as_deref(), Some("d73a4a"));
822        assert_eq!(labels[1].description, None);
823    }
824
825    #[test]
826    fn test_should_deserialize_single_label_from_gh_output() {
827        let json = br#"{"name": "wip", "color": "ffff00", "description": "Work in progress"}"#;
828
829        let label: LabelData = serde_json::from_slice(json).expect("valid LabelData");
830        assert_eq!(label.name, "wip");
831        assert_eq!(label.color.as_deref(), Some("ffff00"));
832        assert_eq!(label.description.as_deref(), Some("Work in progress"));
833    }
834
835    #[test]
836    fn test_should_deserialize_empty_label_list() {
837        let json = b"[]";
838        let labels: Vec<LabelData> =
839            serde_json::from_slice(json).expect("valid empty LabelData list");
840        assert!(labels.is_empty());
841    }
842
843    // --- MilestoneData deserialization tests ---
844
845    #[test]
846    fn test_should_deserialize_milestone_api_response() {
847        let json = br#"{
848            "number": 1,
849            "title": "v1.0 Release",
850            "description": "First stable release",
851            "state": "open",
852            "due_on": "2026-06-01T00:00:00Z",
853            "closed_issues": 10,
854            "open_issues": 5
855        }"#;
856
857        let api: MilestoneApiResponse =
858            serde_json::from_slice(json).expect("valid MilestoneApiResponse");
859        let data: MilestoneData = api.into();
860
861        assert_eq!(data.number, 1);
862        assert_eq!(data.title, "v1.0 Release");
863        assert_eq!(data.description, Some("First stable release".into()));
864        assert_eq!(data.state, State::Open);
865        assert!(data.due_on.is_some());
866        assert_eq!(data.closed_issues, 10);
867        assert_eq!(data.open_issues, 5);
868    }
869
870    #[test]
871    fn test_should_deserialize_closed_milestone() {
872        let json = br#"{
873            "number": 2,
874            "title": "v0.9 Beta",
875            "description": null,
876            "state": "closed",
877            "due_on": null,
878            "closed_issues": 20,
879            "open_issues": 0
880        }"#;
881
882        let api: MilestoneApiResponse =
883            serde_json::from_slice(json).expect("valid MilestoneApiResponse");
884        let data: MilestoneData = api.into();
885
886        assert_eq!(data.state, State::Closed);
887        assert!(data.description.is_none());
888        assert!(data.due_on.is_none());
889    }
890
891    #[test]
892    fn test_should_deserialize_milestone_list() {
893        let json = br#"[
894            {"number": 1, "title": "v1.0", "description": null, "state": "open", "due_on": null, "closed_issues": 0, "open_issues": 3},
895            {"number": 2, "title": "v0.9", "description": "Beta", "state": "closed", "due_on": "2026-01-01T00:00:00Z", "closed_issues": 15, "open_issues": 0}
896        ]"#;
897
898        let milestones: Vec<MilestoneApiResponse> =
899            serde_json::from_slice(json).expect("valid MilestoneApiResponse list");
900        assert_eq!(milestones.len(), 2);
901        assert_eq!(milestones[0].title, "v1.0");
902        assert_eq!(milestones[1].title, "v0.9");
903    }
904
905    #[test]
906    fn test_should_convert_milestone_api_to_data() {
907        let api = MilestoneApiResponse {
908            number: 42,
909            title: "Test Milestone".into(),
910            description: Some("A test".into()),
911            state: "open".into(),
912            due_on: Some("2026-12-01T00:00:00Z".into()),
913            closed_issues: 5,
914            open_issues: 10,
915        };
916
917        let data: MilestoneData = api.clone().into();
918        assert_eq!(data.number, api.number);
919        assert_eq!(data.title, api.title);
920    }
921}