Skip to main content

gitflow_core/
pipeline.rs

1//! Pipeline (CI/CD) 领域类型与平台抽象。
2//!
3//! 定义了流水线状态、任务数据、分析报告的数据表示,以及跨平台
4//! 实现所需的 [`PipelineProvider`] trait。GitHub Actions、GitLab CI、
5//! `GitCode` CI 等平台实现都需实现该 trait,使上层命令层可统一消费。
6
7use async_trait::async_trait;
8use chrono::{DateTime, Utc};
9use serde::{Deserialize, Serialize};
10
11use crate::Result;
12
13/// 流水线状态枚举。
14///
15/// 表示 CI/CD 流水线的当前运行状态。
16#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
17#[serde(rename_all = "snake_case")]
18pub enum PipelineStatusEnum {
19    /// 流水线正在运行。
20    Running,
21    /// 流水线成功完成。
22    Success,
23    /// 流水线失败。
24    Failed,
25    /// 流水线已取消。
26    Cancelled,
27    /// 流水线等待中。
28    Pending,
29}
30
31/// 流水线状态数据。
32///
33/// 由平台实现填充并返回给上层命令。字段命名与平台 API 输出
34/// 的 JSON 字段对齐(camelCase)。
35#[derive(Debug, Clone, Serialize, Deserialize)]
36#[serde(rename_all = "camelCase")]
37pub struct PipelineStatus {
38    /// 流水线编号(平台内唯一)。
39    pub id: u64,
40    /// 触发流水线的分支或标签名。
41    pub ref_name: String,
42    /// 流水线当前状态。
43    pub status: PipelineStatusEnum,
44    /// 流水线结论(成功/失败原因等,可选)。
45    #[serde(skip_serializing_if = "Option::is_none")]
46    pub conclusion: Option<String>,
47    /// 创建时间(UTC)。
48    pub created_at: DateTime<Utc>,
49    /// 最近更新时间(UTC)。
50    pub updated_at: DateTime<Utc>,
51    /// 流水线的 Web URL。
52    pub url: String,
53}
54
55/// 流水线任务(Job)数据。
56///
57/// 表示流水线中的单个任务/步骤的执行信息。
58#[derive(Debug, Clone, Serialize, Deserialize)]
59#[serde(rename_all = "camelCase")]
60pub struct JobData {
61    /// 任务编号(平台内唯一)。
62    pub id: u64,
63    /// 任务名称。
64    pub name: String,
65    /// 任务当前状态(字符串,由平台定义)。
66    pub status: String,
67    /// 任务结论(成功/失败原因等,可选)。
68    #[serde(skip_serializing_if = "Option::is_none")]
69    pub conclusion: Option<String>,
70    /// 任务开始时间(UTC)。
71    #[serde(skip_serializing_if = "Option::is_none")]
72    pub started_at: Option<DateTime<Utc>>,
73    /// 任务完成时间(UTC)。
74    #[serde(skip_serializing_if = "Option::is_none")]
75    pub completed_at: Option<DateTime<Utc>>,
76    /// 任务日志的 Web URL。
77    pub url: String,
78}
79
80/// 流水线分析报告。
81///
82/// 汇总指定分支在一段时间内的流水线运行统计数据。
83#[derive(Debug, Clone, Serialize, Deserialize)]
84#[serde(rename_all = "camelCase")]
85pub struct PipelineReport {
86    /// 总运行次数。
87    pub total_runs: u64,
88    /// 成功率(0.0 ~ 1.0)。
89    pub success_rate: f64,
90    /// 平均运行时长(秒)。
91    pub avg_duration_secs: f64,
92    /// 最常见的失败原因列表。
93    #[serde(default)]
94    pub top_failures: Vec<String>,
95}
96
97/// 流水线(CI/CD)操作的平台抽象。
98///
99/// 所有平台实现(GitHub/GitLab/GitCode)都必须实现此 trait,
100/// 以提供统一的流水线状态查询、日志获取、任务列表和报告生成能力。
101///
102/// # Errors
103///
104/// 所有方法在平台 API 调用失败、反序列化失败或鉴权失败时返回
105/// [`CoreError`](crate::CoreError)。
106///
107/// [`CoreError`]: crate::CoreError
108#[async_trait]
109pub trait PipelineProvider: std::fmt::Debug + Send + Sync {
110    /// 获取指定分支的流水线状态列表。
111    ///
112    /// # Errors
113    ///
114    /// 当平台 API 调用失败或分支不存在时返回错误。
115    async fn status(&self, branch: &str) -> Result<Vec<PipelineStatus>>;
116
117    /// 获取指定流水号的日志文本。
118    ///
119    /// # Errors
120    ///
121    /// 当流水线不存在、日志不可访问或平台 API 调用失败时返回错误。
122    async fn logs(&self, pipeline_id: u64) -> Result<String>;
123
124    /// 获取指定流水线包含的任务列表。
125    ///
126    /// # Errors
127    ///
128    /// 当流水线不存在或平台 API 调用失败时返回错误。
129    async fn jobs(&self, pipeline_id: u64) -> Result<Vec<JobData>>;
130
131    /// 生成指定分支在指定天数内的流水线分析报告。
132    ///
133    /// # Errors
134    ///
135    /// 当分支不存在、平台 API 调用失败或无法生成报告时返回错误。
136    async fn report(&self, branch: &str, days: u32) -> Result<PipelineReport>;
137}
138
139#[cfg(test)]
140mod tests {
141    use super::*;
142
143    #[test]
144    fn test_should_serialize_pipeline_status_enum_to_snake_case() {
145        assert_eq!(
146            serde_json::to_string(&PipelineStatusEnum::Running).expect("serialize"),
147            "\"running\""
148        );
149        assert_eq!(
150            serde_json::to_string(&PipelineStatusEnum::Success).expect("serialize"),
151            "\"success\""
152        );
153        assert_eq!(
154            serde_json::to_string(&PipelineStatusEnum::Failed).expect("serialize"),
155            "\"failed\""
156        );
157        assert_eq!(
158            serde_json::to_string(&PipelineStatusEnum::Cancelled).expect("serialize"),
159            "\"cancelled\""
160        );
161        assert_eq!(
162            serde_json::to_string(&PipelineStatusEnum::Pending).expect("serialize"),
163            "\"pending\""
164        );
165    }
166
167    #[test]
168    fn test_should_deserialize_pipeline_status_enum_from_snake_case() {
169        assert_eq!(
170            serde_json::from_str::<PipelineStatusEnum>("\"running\"").expect("deserialize"),
171            PipelineStatusEnum::Running
172        );
173        assert_eq!(
174            serde_json::from_str::<PipelineStatusEnum>("\"success\"").expect("deserialize"),
175            PipelineStatusEnum::Success
176        );
177        assert_eq!(
178            serde_json::from_str::<PipelineStatusEnum>("\"failed\"").expect("deserialize"),
179            PipelineStatusEnum::Failed
180        );
181        assert_eq!(
182            serde_json::from_str::<PipelineStatusEnum>("\"cancelled\"").expect("deserialize"),
183            PipelineStatusEnum::Cancelled
184        );
185        assert_eq!(
186            serde_json::from_str::<PipelineStatusEnum>("\"pending\"").expect("deserialize"),
187            PipelineStatusEnum::Pending
188        );
189    }
190
191    fn sample_pipeline_status_json() -> &'static str {
192        r#"{
193            "id": 12345,
194            "refName": "main",
195            "status": "success",
196            "conclusion": "all checks passed",
197            "createdAt": "2026-07-01T10:00:00Z",
198            "updatedAt": "2026-07-01T10:05:30Z",
199            "url": "https://github.com/example/repo/actions/runs/12345"
200        }"#
201    }
202
203    #[test]
204    fn test_should_deserialize_pipeline_status_from_json() {
205        let json = sample_pipeline_status_json();
206        let status: PipelineStatus = serde_json::from_str(json).expect("valid PipelineStatus JSON");
207
208        assert_eq!(status.id, 12345);
209        assert_eq!(status.ref_name, "main");
210        assert_eq!(status.status, PipelineStatusEnum::Success);
211        assert_eq!(status.conclusion.as_deref(), Some("all checks passed"));
212        assert_eq!(
213            status.url,
214            "https://github.com/example/repo/actions/runs/12345"
215        );
216    }
217
218    #[test]
219    fn test_should_deserialize_pipeline_status_with_null_conclusion() {
220        let json = r#"{
221            "id": 1,
222            "refName": "develop",
223            "status": "running",
224            "conclusion": null,
225            "createdAt": "2026-07-02T08:00:00Z",
226            "updatedAt": "2026-07-02T08:00:00Z",
227            "url": "https://example.com/1"
228        }"#;
229        let status: PipelineStatus = serde_json::from_str(json).expect("deserialize");
230        assert!(status.conclusion.is_none());
231        assert_eq!(status.status, PipelineStatusEnum::Running);
232    }
233
234    #[test]
235    fn test_should_omit_none_conclusion_on_serialize() {
236        let json = sample_pipeline_status_json();
237        let mut status: PipelineStatus = serde_json::from_str(json).expect("deserialize");
238        status.conclusion = None;
239        let serialized = serde_json::to_string(&status).expect("serialize");
240        assert!(!serialized.contains("\"conclusion\":null"));
241        assert!(!serialized.contains("\"conclusion\": null"));
242    }
243
244    fn sample_job_json() -> &'static str {
245        r#"{
246            "id": 98765,
247            "name": "build",
248            "status": "completed",
249            "conclusion": "success",
250            "startedAt": "2026-07-01T10:00:00Z",
251            "completedAt": "2026-07-01T10:03:00Z",
252            "url": "https://github.com/example/repo/actions/runs/12345/job/98765"
253        }"#
254    }
255
256    #[test]
257    fn test_should_deserialize_job_data_from_json() {
258        let json = sample_job_json();
259        let job: JobData = serde_json::from_str(json).expect("valid JobData JSON");
260
261        assert_eq!(job.id, 98765);
262        assert_eq!(job.name, "build");
263        assert_eq!(job.status, "completed");
264        assert_eq!(job.conclusion.as_deref(), Some("success"));
265        assert_eq!(
266            job.url,
267            "https://github.com/example/repo/actions/runs/12345/job/98765"
268        );
269    }
270
271    #[test]
272    fn test_should_deserialize_job_data_with_null_optional_fields() {
273        let json = r#"{
274            "id": 1,
275            "name": "test",
276            "status": "queued",
277            "conclusion": null,
278            "startedAt": null,
279            "completedAt": null,
280            "url": "https://example.com/job/1"
281        }"#;
282        let job: JobData = serde_json::from_str(json).expect("deserialize");
283        assert!(job.conclusion.is_none());
284        assert!(job.started_at.is_none());
285        assert!(job.completed_at.is_none());
286        assert_eq!(job.status, "queued");
287    }
288
289    #[test]
290    fn test_should_deserialize_job_data_and_roundtrip() {
291        let json = sample_job_json();
292        let job: JobData = serde_json::from_str(json).expect("deserialize");
293        let re_serialized = serde_json::to_string(&job).expect("serialize");
294        let round_tripped: JobData = serde_json::from_str(&re_serialized).expect("re-deserialize");
295
296        assert_eq!(round_tripped.id, job.id);
297        assert_eq!(round_tripped.name, job.name);
298        assert_eq!(round_tripped.status, job.status);
299        assert_eq!(round_tripped.conclusion, job.conclusion);
300        assert_eq!(round_tripped.url, job.url);
301    }
302
303    #[test]
304    fn test_should_build_pipeline_report_and_access_fields() {
305        let report = PipelineReport {
306            total_runs: 100,
307            success_rate: 0.95,
308            avg_duration_secs: 180.5,
309            top_failures: vec!["timeout".into(), "compile error".into()],
310        };
311
312        assert_eq!(report.total_runs, 100);
313        assert!((report.success_rate - 0.95).abs() < f64::EPSILON);
314        assert!((report.avg_duration_secs - 180.5).abs() < f64::EPSILON);
315        assert_eq!(report.top_failures.len(), 2);
316        assert_eq!(report.top_failures[0], "timeout");
317        assert_eq!(report.top_failures[1], "compile error");
318    }
319
320    #[test]
321    fn test_should_serialize_pipeline_report_to_camel_case() {
322        let report = PipelineReport {
323            total_runs: 42,
324            success_rate: 0.8,
325            avg_duration_secs: 120.0,
326            top_failures: vec!["flaky test".into()],
327        };
328        let serialized = serde_json::to_string(&report).expect("serialize");
329
330        // Verify camelCase keys
331        assert!(serialized.contains("\"totalRuns\""));
332        assert!(serialized.contains("\"successRate\""));
333        assert!(serialized.contains("\"avgDurationSecs\""));
334        assert!(serialized.contains("\"topFailures\""));
335    }
336
337    #[test]
338    fn test_should_deserialize_pipeline_report_with_missing_top_failures() {
339        let json = r#"{
340            "totalRuns": 10,
341            "successRate": 1.0,
342            "avgDurationSecs": 60.0
343        }"#;
344        let report: PipelineReport = serde_json::from_str(json).expect("deserialize");
345        assert_eq!(report.total_runs, 10);
346        assert!(report.top_failures.is_empty());
347    }
348}