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, Result,
10    label::{
11        CreateLabelArgs, CreateMilestoneArgs, LabelData, LabelProvider, MilestoneData,
12        MilestoneProvider,
13    },
14    types::State,
15};
16use serde::Deserialize;
17use tracing::debug;
18
19use crate::error::parse_gh_error;
20
21/// GitHub Label 提供者,通过 `gh` CLI 管理仓库标签。
22///
23/// # Examples
24///
25/// ```no_run
26/// use gitflow_github::GitHubLabelProvider;
27///
28/// let provider = GitHubLabelProvider::new("octocat/hello-world");
29/// ```
30#[derive(Debug, Clone)]
31pub struct GitHubLabelProvider {
32    /// GitHub `owner/repo`。
33    repo: String,
34}
35
36impl GitHubLabelProvider {
37    /// 创建新的 GitHub Label 提供者。
38    ///
39    /// `repo` 格式为 `owner/repo`。
40    #[must_use]
41    pub fn new(repo: impl Into<String>) -> Self {
42        Self { repo: repo.into() }
43    }
44}
45
46/// `gh label list/create` 请求的 JSON 字段列表。
47const LABEL_FIELDS: &str = "name,color,description";
48
49#[async_trait]
50impl LabelProvider for GitHubLabelProvider {
51    async fn create(&self, args: CreateLabelArgs) -> Result<LabelData> {
52        debug!(
53            repo = %self.repo,
54            name = %args.name,
55            color = %args.color,
56            "spawning `gh label create`"
57        );
58
59        let mut cmd = tokio::process::Command::new("gh");
60        cmd.args(["label", "create"])
61            .arg(&args.name)
62            .arg("--color")
63            .arg(&args.color)
64            .arg("--repo")
65            .arg(&self.repo);
66
67        if let Some(ref desc) = args.description {
68            cmd.arg("--description").arg(desc);
69        }
70
71        let output = cmd
72            .output()
73            .await
74            .map_err(|e| CoreError::Platform(format!("Failed to spawn gh label create: {e}")))?;
75
76        if !output.status.success() {
77            return Err(parse_gh_error(&output.stderr).into());
78        }
79
80        // gh label create doesn't return JSON, construct the response manually
81        Ok(LabelData {
82            name: args.name,
83            color: Some(args.color),
84            description: args.description,
85        })
86    }
87
88    async fn list(&self) -> Result<Vec<LabelData>> {
89        debug!(repo = %self.repo, "spawning `gh label list`");
90
91        let output = tokio::process::Command::new("gh")
92            .args(["label", "list"])
93            .arg("--repo")
94            .arg(&self.repo)
95            .arg("--json")
96            .arg(LABEL_FIELDS)
97            .output()
98            .await
99            .map_err(|e| CoreError::Platform(format!("Failed to spawn gh label list: {e}")))?;
100
101        if !output.status.success() {
102            return Err(parse_gh_error(&output.stderr).into());
103        }
104
105        let labels: Vec<LabelData> =
106            serde_json::from_slice(&output.stdout).map_err(CoreError::Serialization)?;
107
108        Ok(labels)
109    }
110
111    async fn edit(&self, name: &str, args: CreateLabelArgs) -> Result<LabelData> {
112        debug!(repo = %self.repo, name, "spawning `gh label edit`");
113
114        let mut cmd = tokio::process::Command::new("gh");
115        cmd.args(["label", "edit"])
116            .arg(name)
117            .arg("--repo")
118            .arg(&self.repo)
119            .arg("--color")
120            .arg(&args.color);
121
122        if let Some(ref desc) = args.description {
123            cmd.arg("--description").arg(desc);
124        }
125
126        let output = cmd
127            .output()
128            .await
129            .map_err(|e| CoreError::Platform(format!("Failed to spawn gh label edit: {e}")))?;
130
131        if !output.status.success() {
132            return Err(parse_gh_error(&output.stderr).into());
133        }
134
135        // gh label edit 不返回 JSON,重新 fetch 获取最新数据
136        self.fetch_label(name).await
137    }
138
139    async fn delete(&self, name: &str) -> Result<()> {
140        debug!(repo = %self.repo, name, "spawning `gh label delete`");
141
142        let output = tokio::process::Command::new("gh")
143            .args(["label", "delete"])
144            .arg(name)
145            .arg("--yes")
146            .arg("--repo")
147            .arg(&self.repo)
148            .output()
149            .await
150            .map_err(|e| CoreError::Platform(format!("Failed to spawn gh label delete: {e}")))?;
151
152        if !output.status.success() {
153            return Err(parse_gh_error(&output.stderr).into());
154        }
155
156        Ok(())
157    }
158}
159
160impl GitHubLabelProvider {
161    /// 获取指定名称的标签数据(内部辅助方法)。
162    async fn fetch_label(&self, name: &str) -> Result<LabelData> {
163        let output = tokio::process::Command::new("gh")
164            .args(["label", "view"])
165            .arg(name)
166            .arg("--repo")
167            .arg(&self.repo)
168            .arg("--json")
169            .arg(LABEL_FIELDS)
170            .output()
171            .await
172            .map_err(|e| CoreError::Platform(format!("Failed to spawn gh label view: {e}")))?;
173
174        if !output.status.success() {
175            return Err(parse_gh_error(&output.stderr).into());
176        }
177
178        let label: LabelData =
179            serde_json::from_slice(&output.stdout).map_err(CoreError::Serialization)?;
180
181        Ok(label)
182    }
183}
184
185/// GitHub 里程碑提供者,通过 `gh api` 管理仓库里程碑。
186///
187/// # Examples
188///
189/// ```no_run
190/// use gitflow_github::GitHubMilestoneProvider;
191///
192/// let provider = GitHubMilestoneProvider::new("octocat/hello-world");
193/// ```
194#[derive(Debug, Clone)]
195pub struct GitHubMilestoneProvider {
196    /// GitHub `owner/repo`。
197    repo: String,
198}
199
200impl GitHubMilestoneProvider {
201    /// 创建新的 GitHub Milestone 提供者。
202    ///
203    /// `repo` 格式为 `owner/repo`。
204    #[must_use]
205    pub fn new(repo: impl Into<String>) -> Self {
206        Self { repo: repo.into() }
207    }
208}
209
210/// `gh api milestones` 返回的 JSON 结构。
211#[derive(Debug, Clone, Deserialize)]
212#[serde(rename_all = "camelCase")]
213struct MilestoneApiResponse {
214    number: u64,
215    title: String,
216    #[serde(default)]
217    description: Option<String>,
218    state: String,
219    #[serde(default)]
220    due_on: Option<String>,
221    #[serde(default)]
222    closed_issues: u64,
223    #[serde(default)]
224    open_issues: u64,
225}
226
227impl From<MilestoneApiResponse> for MilestoneData {
228    fn from(api: MilestoneApiResponse) -> Self {
229        Self {
230            number: api.number,
231            title: api.title,
232            description: api.description,
233            state: if api.state == "closed" {
234                State::Closed
235            } else {
236                State::Open
237            },
238            due_on: api.due_on.and_then(|s| {
239                DateTime::parse_from_rfc3339(&s).map_or(None, |dt| Some(dt.with_timezone(&Utc)))
240            }),
241            closed_issues: api.closed_issues,
242            open_issues: api.open_issues,
243        }
244    }
245}
246
247#[async_trait]
248impl MilestoneProvider for GitHubMilestoneProvider {
249    async fn create(&self, args: CreateMilestoneArgs) -> Result<MilestoneData> {
250        debug!(repo = %self.repo, title = %args.title, "spawning `gh api milestones POST`");
251
252        let api_path = format!("repos/{repo}/milestones", repo = self.repo);
253
254        let mut cmd = tokio::process::Command::new("gh");
255        cmd.args(["api", &api_path, "-X", "POST"])
256            .arg("-f")
257            .arg(format!("title={}", args.title));
258
259        if let Some(ref desc) = args.description {
260            cmd.arg("-f").arg(format!("description={desc}"));
261        }
262
263        if let Some(ref due) = args.due_on {
264            cmd.arg("-f").arg(format!("due_on={}", due.to_rfc3339()));
265        }
266
267        let output = cmd
268            .output()
269            .await
270            .map_err(|e| CoreError::Platform(format!("Failed to spawn gh api milestones: {e}")))?;
271
272        if !output.status.success() {
273            return Err(parse_gh_error(&output.stderr).into());
274        }
275
276        let api_response: MilestoneApiResponse =
277            serde_json::from_slice(&output.stdout).map_err(CoreError::Serialization)?;
278
279        Ok(api_response.into())
280    }
281
282    async fn list(&self) -> Result<Vec<MilestoneData>> {
283        debug!(repo = %self.repo, "spawning `gh api milestones list`");
284
285        let api_path = format!("repos/{repo}/milestones", repo = self.repo);
286
287        let output = tokio::process::Command::new("gh")
288            .args(["api", &api_path])
289            .output()
290            .await
291            .map_err(|e| CoreError::Platform(format!("Failed to spawn gh api milestones: {e}")))?;
292
293        if !output.status.success() {
294            return Err(parse_gh_error(&output.stderr).into());
295        }
296
297        let milestones: Vec<MilestoneApiResponse> =
298            serde_json::from_slice(&output.stdout).map_err(CoreError::Serialization)?;
299
300        Ok(milestones.into_iter().map(MilestoneData::from).collect())
301    }
302
303    async fn edit(&self, number: u64, args: CreateMilestoneArgs) -> Result<MilestoneData> {
304        debug!(repo = %self.repo, number, "spawning `gh api milestones PATCH`");
305
306        let api_path = format!("repos/{repo}/milestones/{number}", repo = self.repo);
307
308        let mut cmd = tokio::process::Command::new("gh");
309        cmd.args(["api", &api_path, "-X", "PATCH"]);
310
311        cmd.arg("-f").arg(format!("title={}", args.title));
312
313        if let Some(ref desc) = args.description {
314            cmd.arg("-f").arg(format!("description={desc}"));
315        }
316
317        if let Some(ref due) = args.due_on {
318            cmd.arg("-f").arg(format!("due_on={}", due.to_rfc3339()));
319        }
320
321        let output = cmd.output().await.map_err(|e| {
322            CoreError::Platform(format!("Failed to spawn gh api milestone edit: {e}"))
323        })?;
324
325        if !output.status.success() {
326            return Err(parse_gh_error(&output.stderr).into());
327        }
328
329        let api_response: MilestoneApiResponse =
330            serde_json::from_slice(&output.stdout).map_err(CoreError::Serialization)?;
331
332        Ok(api_response.into())
333    }
334
335    async fn close(&self, number: u64) -> Result<MilestoneData> {
336        debug!(repo = %self.repo, number, "spawning `gh api milestones close`");
337
338        let api_path = format!("repos/{repo}/milestones/{number}", repo = self.repo);
339
340        let output = tokio::process::Command::new("gh")
341            .args(["api", &api_path, "-X", "PATCH", "-f", "state=closed"])
342            .output()
343            .await
344            .map_err(|e| {
345                CoreError::Platform(format!("Failed to spawn gh api milestone close: {e}"))
346            })?;
347
348        if !output.status.success() {
349            return Err(parse_gh_error(&output.stderr).into());
350        }
351
352        let api_response: MilestoneApiResponse =
353            serde_json::from_slice(&output.stdout).map_err(CoreError::Serialization)?;
354
355        Ok(api_response.into())
356    }
357
358    async fn reopen(&self, number: u64) -> Result<MilestoneData> {
359        debug!(repo = %self.repo, number, "spawning `gh api milestones reopen`");
360
361        let api_path = format!("repos/{repo}/milestones/{number}", repo = self.repo);
362
363        let output = tokio::process::Command::new("gh")
364            .args(["api", &api_path, "-X", "PATCH", "-f", "state=open"])
365            .output()
366            .await
367            .map_err(|e| {
368                CoreError::Platform(format!("Failed to spawn gh api milestone reopen: {e}"))
369            })?;
370
371        if !output.status.success() {
372            return Err(parse_gh_error(&output.stderr).into());
373        }
374
375        let api_response: MilestoneApiResponse =
376            serde_json::from_slice(&output.stdout).map_err(CoreError::Serialization)?;
377
378        Ok(api_response.into())
379    }
380}
381
382#[cfg(test)]
383mod tests {
384    use super::*;
385
386    // --- GitHubLabelProvider tests ---
387
388    #[test]
389    fn test_should_construct_github_label_provider() {
390        let provider = GitHubLabelProvider::new("octocat/hello-world");
391        assert_eq!(provider.repo, "octocat/hello-world");
392    }
393
394    #[test]
395    fn test_should_construct_github_label_provider_from_string() {
396        let repo = String::from("octocat/hello-world");
397        let provider = GitHubLabelProvider::new(repo);
398        assert_eq!(provider.repo, "octocat/hello-world");
399    }
400
401    #[test]
402    fn test_should_debug_format_label_provider() {
403        let provider = GitHubLabelProvider::new("owner/repo");
404        let debug = format!("{provider:?}");
405        assert!(debug.contains("GitHubLabelProvider"));
406        assert!(debug.contains("owner/repo"));
407    }
408
409    #[test]
410    fn test_should_clone_github_label_provider() {
411        let original = GitHubLabelProvider::new("owner/repo");
412        let cloned = original.clone();
413        assert_eq!(original.repo, cloned.repo);
414    }
415
416    // --- GitHubMilestoneProvider tests ---
417
418    #[test]
419    fn test_should_construct_github_milestone_provider() {
420        let provider = GitHubMilestoneProvider::new("octocat/hello-world");
421        assert_eq!(provider.repo, "octocat/hello-world");
422    }
423
424    #[test]
425    fn test_should_debug_format_milestone_provider() {
426        let provider = GitHubMilestoneProvider::new("owner/repo");
427        let debug = format!("{provider:?}");
428        assert!(debug.contains("GitHubMilestoneProvider"));
429        assert!(debug.contains("owner/repo"));
430    }
431
432    #[test]
433    fn test_should_clone_github_milestone_provider() {
434        let original = GitHubMilestoneProvider::new("owner/repo");
435        let cloned = original.clone();
436        assert_eq!(original.repo, cloned.repo);
437    }
438
439    // --- LabelData deserialization tests ---
440
441    #[test]
442    fn test_should_deserialize_label_data_from_gh_output() {
443        let json = br#"[
444            {"name": "bug", "color": "d73a4a", "description": "Something isn't working"},
445            {"name": "enhancement", "color": "a2eeef", "description": null}
446        ]"#;
447
448        let labels: Vec<LabelData> = serde_json::from_slice(json).expect("valid LabelData list");
449        assert_eq!(labels.len(), 2);
450        assert_eq!(labels[0].name, "bug");
451        assert_eq!(labels[0].color.as_deref(), Some("d73a4a"));
452        assert_eq!(labels[1].description, None);
453    }
454
455    #[test]
456    fn test_should_deserialize_single_label_from_gh_output() {
457        let json = br#"{"name": "wip", "color": "ffff00", "description": "Work in progress"}"#;
458
459        let label: LabelData = serde_json::from_slice(json).expect("valid LabelData");
460        assert_eq!(label.name, "wip");
461        assert_eq!(label.color.as_deref(), Some("ffff00"));
462        assert_eq!(label.description.as_deref(), Some("Work in progress"));
463    }
464
465    #[test]
466    fn test_should_deserialize_empty_label_list() {
467        let json = b"[]";
468        let labels: Vec<LabelData> =
469            serde_json::from_slice(json).expect("valid empty LabelData list");
470        assert!(labels.is_empty());
471    }
472
473    // --- MilestoneData deserialization tests ---
474
475    #[test]
476    fn test_should_deserialize_milestone_api_response() {
477        let json = br#"{
478            "number": 1,
479            "title": "v1.0 Release",
480            "description": "First stable release",
481            "state": "open",
482            "dueOn": "2026-06-01T00:00:00Z",
483            "closedIssues": 10,
484            "openIssues": 5
485        }"#;
486
487        let api: MilestoneApiResponse =
488            serde_json::from_slice(json).expect("valid MilestoneApiResponse");
489        let data: MilestoneData = api.into();
490
491        assert_eq!(data.number, 1);
492        assert_eq!(data.title, "v1.0 Release");
493        assert_eq!(data.description, Some("First stable release".into()));
494        assert_eq!(data.state, State::Open);
495        assert!(data.due_on.is_some());
496        assert_eq!(data.closed_issues, 10);
497        assert_eq!(data.open_issues, 5);
498    }
499
500    #[test]
501    fn test_should_deserialize_closed_milestone() {
502        let json = br#"{
503            "number": 2,
504            "title": "v0.9 Beta",
505            "description": null,
506            "state": "closed",
507            "dueOn": null,
508            "closedIssues": 20,
509            "openIssues": 0
510        }"#;
511
512        let api: MilestoneApiResponse =
513            serde_json::from_slice(json).expect("valid MilestoneApiResponse");
514        let data: MilestoneData = api.into();
515
516        assert_eq!(data.state, State::Closed);
517        assert!(data.description.is_none());
518        assert!(data.due_on.is_none());
519    }
520
521    #[test]
522    fn test_should_deserialize_milestone_list() {
523        let json = br#"[
524            {"number": 1, "title": "v1.0", "description": null, "state": "open", "dueOn": null, "closedIssues": 0, "openIssues": 3},
525            {"number": 2, "title": "v0.9", "description": "Beta", "state": "closed", "dueOn": "2026-01-01T00:00:00Z", "closedIssues": 15, "openIssues": 0}
526        ]"#;
527
528        let milestones: Vec<MilestoneApiResponse> =
529            serde_json::from_slice(json).expect("valid MilestoneApiResponse list");
530        assert_eq!(milestones.len(), 2);
531        assert_eq!(milestones[0].title, "v1.0");
532        assert_eq!(milestones[1].title, "v0.9");
533    }
534
535    #[test]
536    fn test_should_convert_milestone_api_to_data() {
537        let api = MilestoneApiResponse {
538            number: 42,
539            title: "Test Milestone".into(),
540            description: Some("A test".into()),
541            state: "open".into(),
542            due_on: Some("2026-12-01T00:00:00Z".into()),
543            closed_issues: 5,
544            open_issues: 10,
545        };
546
547        let data: MilestoneData = api.clone().into();
548        assert_eq!(data.number, api.number);
549        assert_eq!(data.title, api.title);
550    }
551}