Skip to main content

gitflow_core/
label.rs

1//! Label and Milestone resource types with platform abstraction.
2//!
3//! Defines data types for managing repository labels and milestones,
4//! along with [`LabelProvider`] and [`MilestoneProvider`] traits for
5//! cross-platform implementations (GitHub, GitLab, `GitCode`, etc.).
6
7use async_trait::async_trait;
8use chrono::{DateTime, Utc};
9use serde::{Deserialize, Serialize};
10
11use crate::{Result, paging::Paged, types::State};
12
13/// A standalone label resource definition.
14///
15/// Unlike [`crate::types::Label`] which represents a label *association*
16/// on an Issue or PR, this type represents the label resource itself —
17/// its name, display color, and description as managed in the repository.
18#[derive(Debug, Clone, Serialize, Deserialize)]
19#[serde(rename_all = "camelCase")]
20pub struct LabelData {
21    /// The label name.
22    pub name: String,
23    /// The label color as a hex string (e.g. `"d73a4a"`).
24    #[serde(skip_serializing_if = "Option::is_none")]
25    pub color: Option<String>,
26    /// A human-readable description of the label.
27    #[serde(skip_serializing_if = "Option::is_none")]
28    pub description: Option<String>,
29}
30
31/// Arguments for creating a new label.
32#[derive(Debug, Clone)]
33pub struct CreateLabelArgs {
34    /// The label name.
35    pub name: String,
36    /// The label color as a hex string (e.g. `"d73a4a"`).
37    pub color: String,
38    /// A human-readable description of the label.
39    pub description: Option<String>,
40}
41
42/// A milestone resource definition.
43///
44/// Milestones group issues and PRs under a shared goal or release
45/// target with optional due dates and progress tracking.
46#[derive(Debug, Clone, Serialize, Deserialize)]
47#[serde(rename_all = "camelCase")]
48pub struct MilestoneData {
49    /// The milestone's numeric identifier.
50    pub number: u64,
51    /// The milestone title.
52    pub title: String,
53    /// The milestone description (Markdown).
54    #[serde(skip_serializing_if = "Option::is_none")]
55    pub description: Option<String>,
56    /// The milestone's current state.
57    pub state: State,
58    /// The optional due date (UTC).
59    #[serde(skip_serializing_if = "Option::is_none")]
60    pub due_on: Option<DateTime<Utc>>,
61    /// The number of closed issues under this milestone.
62    pub closed_issues: u64,
63    /// The number of open issues under this milestone.
64    pub open_issues: u64,
65}
66
67/// Arguments for creating a new milestone.
68#[derive(Debug, Clone)]
69pub struct CreateMilestoneArgs {
70    /// The milestone title.
71    pub title: String,
72    /// The milestone description (Markdown).
73    pub description: Option<String>,
74    /// The optional due date (UTC).
75    pub due_on: Option<DateTime<Utc>>,
76}
77
78/// Platform abstraction for label management.
79///
80/// All platform implementations (GitHub/GitLab/GitCode) must implement
81/// this trait to provide unified label CRUD operations.
82///
83/// # Errors
84///
85/// All methods return [`CoreError`](crate::CoreError) on platform API
86/// failure, deserialization errors, or authentication failures.
87#[async_trait]
88pub trait LabelProvider: std::fmt::Debug + Send + Sync {
89    /// Create a new label in the repository.
90    ///
91    /// # Errors
92    ///
93    /// Returns an error if the platform API call fails, the label name
94    /// already exists, or the parameters are invalid.
95    async fn create(&self, args: CreateLabelArgs) -> Result<LabelData>;
96
97    /// List all labels in the repository.
98    ///
99    /// `limit` 为 `None` 时取至 [`crate::paging::DEFAULT_LIST_LIMIT`]。
100    ///
101    /// # Errors
102    ///
103    /// Returns an error if the platform API call fails.
104    async fn list(&self, limit: Option<u32>) -> Result<Paged<LabelData>>;
105
106    /// Edit an existing label by name.
107    ///
108    /// # Errors
109    ///
110    /// Returns an error if the label does not exist or the platform API call fails.
111    async fn edit(&self, name: &str, args: CreateLabelArgs) -> Result<LabelData>;
112
113    /// Delete a label by name.
114    ///
115    /// # Errors
116    ///
117    /// Returns an error if the label does not exist or the platform API call fails.
118    async fn delete(&self, name: &str) -> Result<()>;
119}
120
121/// Platform abstraction for milestone management.
122///
123/// All platform implementations (GitHub/GitLab/GitCode) must implement
124/// this trait to provide unified milestone lifecycle operations.
125///
126/// # Errors
127///
128/// All methods return [`CoreError`](crate::CoreError) on platform API
129/// failure, deserialization errors, or authentication failures.
130#[async_trait]
131pub trait MilestoneProvider: std::fmt::Debug + Send + Sync {
132    /// Create a new milestone.
133    ///
134    /// # Errors
135    ///
136    /// Returns an error if the platform API call fails or the parameters are invalid.
137    async fn create(&self, args: CreateMilestoneArgs) -> Result<MilestoneData>;
138
139    /// List all milestones in the repository.
140    ///
141    /// `limit` 为 `None` 时取至 [`crate::paging::DEFAULT_LIST_LIMIT`]。
142    ///
143    /// # Errors
144    ///
145    /// Returns an error if the platform API call fails.
146    async fn list(&self, limit: Option<u32>) -> Result<Paged<MilestoneData>>;
147
148    /// Edit an existing milestone by number.
149    ///
150    /// # Errors
151    ///
152    /// Returns an error if the milestone does not exist or the platform API call fails.
153    async fn edit(&self, number: u64, args: CreateMilestoneArgs) -> Result<MilestoneData>;
154
155    /// Close a milestone by number.
156    ///
157    /// # Errors
158    ///
159    /// Returns an error if the milestone does not exist or the platform API call fails.
160    async fn close(&self, number: u64) -> Result<MilestoneData>;
161
162    /// Reopen a closed milestone by number.
163    ///
164    /// # Errors
165    ///
166    /// Returns an error if the milestone does not exist or the platform API call fails.
167    async fn reopen(&self, number: u64) -> Result<MilestoneData>;
168}
169
170/// Resolves a user-supplied milestone identifier (`--milestone <NUMBER|TITLE>`)
171/// against the repository's milestone list, matching by number first (if the
172/// identifier parses as `u64`) then by exact title.
173///
174/// # Errors
175///
176/// Returns an error if no milestone matches by either number or exact title.
177pub async fn resolve_milestone_identifier(
178    provider: &dyn MilestoneProvider,
179    identifier: &str,
180) -> Result<crate::types::MilestoneRef> {
181    let milestones = provider.list(None).await?;
182    if let Ok(number) = identifier.parse::<u64>()
183        && let Some(m) = milestones.items.iter().find(|m| m.number == number)
184    {
185        return Ok(crate::types::MilestoneRef {
186            number: m.number,
187            title: m.title.clone(),
188        });
189    }
190    milestones
191        .items
192        .iter()
193        .find(|m| m.title == identifier)
194        .map(|m| crate::types::MilestoneRef {
195            number: m.number,
196            title: m.title.clone(),
197        })
198        .ok_or_else(|| {
199            crate::CoreError::Platform(format!(
200                "milestone '{identifier}' not found (matched by neither number nor exact title)"
201            ))
202        })
203}
204
205#[cfg(test)]
206mod tests {
207    use super::*;
208
209    // --- LabelData tests ---
210
211    #[test]
212    fn test_should_serialize_label_data_to_camel_case_json() {
213        let label = LabelData {
214            name: "bug".into(),
215            color: Some("d73a4a".into()),
216            description: Some("Something isn't working".into()),
217        };
218        let json = serde_json::to_string(&label).expect("serialize LabelData");
219        assert!(json.contains("\"name\":\"bug\""));
220        assert!(json.contains("\"color\":\"d73a4a\""));
221        assert!(json.contains("\"description\""));
222    }
223
224    #[test]
225    fn test_should_deserialize_label_data_from_camel_case_json() {
226        let json = r#"{"name":"enhancement","color":"a2eeef","description":"New feature"}"#;
227        let label: LabelData = serde_json::from_str(json).expect("valid LabelData");
228        assert_eq!(label.name, "enhancement");
229        assert_eq!(label.color, Some("a2eeef".into()));
230        assert_eq!(label.description, Some("New feature".into()));
231    }
232
233    #[test]
234    fn test_should_deserialize_label_data_with_missing_optional_fields() {
235        let json = r#"{"name":"wip"}"#;
236        let label: LabelData = serde_json::from_str(json).expect("valid LabelData");
237        assert_eq!(label.name, "wip");
238        assert!(label.color.is_none());
239        assert!(label.description.is_none());
240    }
241
242    #[test]
243    fn test_should_serialize_label_data_skips_null_fields() {
244        let label = LabelData {
245            name: "wip".into(),
246            color: None,
247            description: None,
248        };
249        let json = serde_json::to_string(&label).expect("serialize LabelData");
250        assert_eq!(json, r#"{"name":"wip"}"#);
251        assert!(!json.contains("null"));
252    }
253
254    #[test]
255    fn test_should_roundtrip_label_data_via_serde() {
256        let label = LabelData {
257            name: "bug".into(),
258            color: Some("ff0000".into()),
259            description: Some("A defect".into()),
260        };
261        let json = serde_json::to_string(&label).expect("serialize");
262        let round_tripped: LabelData = serde_json::from_str(&json).expect("deserialize");
263        assert_eq!(round_tripped.name, label.name);
264        assert_eq!(round_tripped.color, label.color);
265        assert_eq!(round_tripped.description, label.description);
266    }
267
268    #[test]
269    fn test_should_derive_debug_for_label_data() {
270        let label = LabelData {
271            name: "test".into(),
272            color: None,
273            description: None,
274        };
275        let debug = format!("{label:?}");
276        assert!(debug.contains("LabelData"));
277        assert!(debug.contains("test"));
278    }
279
280    // --- CreateLabelArgs tests ---
281
282    #[test]
283    fn test_should_create_label_args_with_description() {
284        let args = CreateLabelArgs {
285            name: "bug".into(),
286            color: "d73a4a".into(),
287            description: Some("Defect report".into()),
288        };
289        assert_eq!(args.name, "bug");
290        assert_eq!(args.color, "d73a4a");
291        assert_eq!(args.description, Some("Defect report".into()));
292    }
293
294    #[test]
295    fn test_should_create_label_args_without_description() {
296        let args = CreateLabelArgs {
297            name: "wip".into(),
298            color: "ffff00".into(),
299            description: None,
300        };
301        assert_eq!(args.name, "wip");
302        assert!(args.description.is_none());
303    }
304
305    // --- MilestoneData tests ---
306
307    fn sample_milestone_json() -> &'static str {
308        r#"{
309            "number": 1,
310            "title": "v1.0 Release",
311            "description": "First stable release",
312            "state": "open",
313            "dueOn": "2026-06-01T00:00:00Z",
314            "closedIssues": 10,
315            "openIssues": 5
316        }"#
317    }
318
319    #[test]
320    fn test_should_deserialize_milestone_data_from_camel_case_json() {
321        let json = sample_milestone_json();
322        let milestone: MilestoneData = serde_json::from_str(json).expect("valid MilestoneData");
323        assert_eq!(milestone.number, 1);
324        assert_eq!(milestone.title, "v1.0 Release");
325        assert_eq!(milestone.description, Some("First stable release".into()));
326        assert_eq!(milestone.state, State::Open);
327        assert!(milestone.due_on.is_some());
328        assert_eq!(milestone.closed_issues, 10);
329        assert_eq!(milestone.open_issues, 5);
330    }
331
332    #[test]
333    fn test_should_serialize_milestone_data_to_camel_case_json() {
334        let json = sample_milestone_json();
335        let milestone: MilestoneData = serde_json::from_str(json).expect("deserialize");
336        let serialized = serde_json::to_string(&milestone).expect("serialize");
337        assert!(serialized.contains("\"closedIssues\""));
338        assert!(serialized.contains("\"openIssues\""));
339        assert!(serialized.contains("\"dueOn\""));
340        assert!(!serialized.contains("\"closed_issues\""));
341        assert!(!serialized.contains("\"open_issues\""));
342    }
343
344    #[test]
345    fn test_should_roundtrip_milestone_data_via_serde() {
346        let json = sample_milestone_json();
347        let milestone: MilestoneData = serde_json::from_str(json).expect("deserialize");
348        let re_serialized = serde_json::to_string(&milestone).expect("serialize");
349        let round_tripped: MilestoneData =
350            serde_json::from_str(&re_serialized).expect("re-deserialize");
351        assert_eq!(round_tripped.number, milestone.number);
352        assert_eq!(round_tripped.title, milestone.title);
353        assert_eq!(round_tripped.description, milestone.description);
354        assert_eq!(round_tripped.state, milestone.state);
355        assert_eq!(round_tripped.due_on, milestone.due_on);
356        assert_eq!(round_tripped.closed_issues, milestone.closed_issues);
357        assert_eq!(round_tripped.open_issues, milestone.open_issues);
358    }
359
360    #[test]
361    fn test_should_deserialize_milestone_with_null_optional_fields() {
362        let json = r#"{
363            "number": 2,
364            "title": "v1.1",
365            "description": null,
366            "state": "closed",
367            "dueOn": null,
368            "closedIssues": 20,
369            "openIssues": 0
370        }"#;
371        let milestone: MilestoneData = serde_json::from_str(json).expect("deserialize");
372        assert!(milestone.description.is_none());
373        assert!(milestone.due_on.is_none());
374        assert_eq!(milestone.state, State::Closed);
375    }
376
377    #[test]
378    fn test_should_serialize_milestone_skips_null_fields() {
379        let milestone = MilestoneData {
380            number: 3,
381            title: "Future".into(),
382            description: None,
383            state: State::Open,
384            due_on: None,
385            closed_issues: 0,
386            open_issues: 3,
387        };
388        let json = serde_json::to_string(&milestone).expect("serialize");
389        assert!(!json.contains("null"));
390        assert!(!json.contains("\"description\":null"));
391        assert!(!json.contains("\"dueOn\":null"));
392    }
393
394    #[test]
395    fn test_should_derive_debug_for_milestone_data() {
396        let milestone = MilestoneData {
397            number: 1,
398            title: "v1.0".into(),
399            description: None,
400            state: State::Open,
401            due_on: None,
402            closed_issues: 0,
403            open_issues: 1,
404        };
405        let debug = format!("{milestone:?}");
406        assert!(debug.contains("MilestoneData"));
407        assert!(debug.contains("v1.0"));
408    }
409
410    // --- CreateMilestoneArgs tests ---
411
412    #[test]
413    fn test_should_create_milestone_args_with_all_fields() {
414        let args = CreateMilestoneArgs {
415            title: "v2.0".into(),
416            description: Some("Major release".into()),
417            due_on: Some("2026-12-01T00:00:00Z".parse().expect("valid date")),
418        };
419        assert_eq!(args.title, "v2.0");
420        assert_eq!(args.description, Some("Major release".into()));
421        assert!(args.due_on.is_some());
422    }
423
424    #[test]
425    fn test_should_create_milestone_args_minimal() {
426        let args = CreateMilestoneArgs {
427            title: "Backlog".into(),
428            description: None,
429            due_on: None,
430        };
431        assert_eq!(args.title, "Backlog");
432        assert!(args.description.is_none());
433        assert!(args.due_on.is_none());
434    }
435
436    // --- resolve_milestone_identifier tests ---
437
438    #[derive(Debug)]
439    struct MockMilestoneProvider {
440        milestones: Vec<MilestoneData>,
441    }
442
443    #[async_trait::async_trait]
444    impl MilestoneProvider for MockMilestoneProvider {
445        async fn create(&self, _args: CreateMilestoneArgs) -> Result<MilestoneData> {
446            unimplemented!("not used by resolver tests")
447        }
448        async fn list(&self, _limit: Option<u32>) -> Result<Paged<MilestoneData>> {
449            Ok(Paged {
450                items: self.milestones.clone(),
451                truncated: false,
452                limit: 100,
453            })
454        }
455        async fn edit(&self, _number: u64, _args: CreateMilestoneArgs) -> Result<MilestoneData> {
456            unimplemented!("not used by resolver tests")
457        }
458        async fn close(&self, _number: u64) -> Result<MilestoneData> {
459            unimplemented!("not used by resolver tests")
460        }
461        async fn reopen(&self, _number: u64) -> Result<MilestoneData> {
462            unimplemented!("not used by resolver tests")
463        }
464    }
465
466    fn sample_milestone(number: u64, title: &str) -> MilestoneData {
467        MilestoneData {
468            number,
469            title: title.to_string(),
470            description: None,
471            state: State::Open,
472            due_on: None,
473            closed_issues: 0,
474            open_issues: 0,
475        }
476    }
477
478    #[tokio::test]
479    async fn test_should_resolve_milestone_by_number() {
480        let provider = MockMilestoneProvider {
481            milestones: vec![sample_milestone(1, "v1.0"), sample_milestone(2, "v2.0")],
482        };
483        let resolved = resolve_milestone_identifier(&provider, "2")
484            .await
485            .expect("resolve");
486        assert_eq!(
487            resolved,
488            crate::types::MilestoneRef {
489                number: 2,
490                title: "v2.0".into()
491            }
492        );
493    }
494
495    #[tokio::test]
496    async fn test_should_resolve_milestone_by_title() {
497        let provider = MockMilestoneProvider {
498            milestones: vec![sample_milestone(1, "v1.0"), sample_milestone(2, "v2.0")],
499        };
500        let resolved = resolve_milestone_identifier(&provider, "v1.0")
501            .await
502            .expect("resolve");
503        assert_eq!(
504            resolved,
505            crate::types::MilestoneRef {
506                number: 1,
507                title: "v1.0".into()
508            }
509        );
510    }
511
512    #[tokio::test]
513    async fn test_should_prefer_number_match_over_title_match() {
514        // Identifier "2" happens to also be a different milestone's title.
515        let provider = MockMilestoneProvider {
516            milestones: vec![sample_milestone(1, "2"), sample_milestone(2, "v2.0")],
517        };
518        let resolved = resolve_milestone_identifier(&provider, "2")
519            .await
520            .expect("resolve");
521        assert_eq!(
522            resolved.number, 2,
523            "numeric identifier must match by number first, not by a milestone whose title \
524             happens to equal the same string"
525        );
526    }
527
528    #[tokio::test]
529    async fn test_should_error_when_milestone_identifier_not_found() {
530        let provider = MockMilestoneProvider {
531            milestones: vec![sample_milestone(1, "v1.0")],
532        };
533        let result = resolve_milestone_identifier(&provider, "does-not-exist").await;
534        assert!(result.is_err());
535    }
536}