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