Skip to main content

gitflow_core/
compatibility.rs

1//! 兼容性矩阵数据。
2//!
3//! 从 crate 内的 `resources/compatibility-matrix.json` 编译时嵌入,
4//! 提供各平台 CLI 版本要求和功能覆盖信息。
5//!
6//! 数据文件位于 crate 内部(而非仓库根 `docs/`),确保 `cargo publish`
7//! 打包的 tarball 自包含——`include_str!` 无法引用 crate 目录外的文件。
8
9use serde::Deserialize;
10
11/// 编译时嵌入的兼容性矩阵 JSON。
12const MATRIX_JSON: &str = include_str!("../resources/compatibility-matrix.json");
13
14/// 兼容性矩阵根结构。
15#[derive(Debug, Deserialize)]
16struct MatrixRoot {
17    /// 矩阵 schema 版本。
18    #[allow(
19        dead_code,
20        reason = "Deserialized for validation, not yet used at runtime"
21    )]
22    schema_version: u32,
23    /// 最后更新日期。
24    #[allow(
25        dead_code,
26        reason = "Deserialized for validation, not yet used at runtime"
27    )]
28    updated_at: String,
29    /// 平台列表。
30    platforms: Vec<PlatformCompat>,
31}
32
33/// 单个平台的兼容性信息。
34#[derive(Debug, Clone, Deserialize)]
35pub struct PlatformCompat {
36    /// 平台显示名称(如 `"GitHub"`)。
37    pub name: String,
38    /// 平台标识符(如 `"github"`)。
39    pub identifier: String,
40    /// CLI 可执行文件名(如 `"gh"`)。
41    pub cli_binary: String,
42    /// 最低版本号(semver)。
43    pub min_version: String,
44    /// 已测试的版本列表。
45    pub tested_versions: Vec<String>,
46    /// 官方安装指引链接。
47    pub install_url: String,
48    /// 文档链接。
49    pub doc_link: String,
50}
51
52/// 获取所有平台的兼容性信息。
53///
54/// # Panics
55///
56/// 当嵌入的 JSON 格式无效时 panic(编译时数据损坏,属于不可恢复错误)。
57#[must_use]
58#[allow(
59    clippy::expect_used,
60    reason = "Embedded JSON is compile-time data; parse failure means corrupted build artifacts"
61)]
62pub fn platform_compatibility() -> Vec<PlatformCompat> {
63    let root: MatrixRoot =
64        serde_json::from_str(MATRIX_JSON).expect("embedded compatibility-matrix.json is invalid");
65    root.platforms
66}
67
68/// 获取指定平台的兼容性信息。
69#[must_use]
70pub fn platform_requirement(identifier: &str) -> Option<PlatformCompat> {
71    platform_compatibility()
72        .into_iter()
73        .find(|p| p.identifier == identifier)
74}
75
76#[cfg(test)]
77mod tests {
78    use super::*;
79
80    #[test]
81    fn test_should_load_all_three_platforms() {
82        let platforms = platform_compatibility();
83        assert_eq!(platforms.len(), 3);
84    }
85
86    #[test]
87    fn test_should_return_github_requirement() {
88        let gh = platform_requirement("github").expect("github should exist");
89        assert_eq!(gh.cli_binary, "gh");
90        assert_eq!(gh.min_version, "2.0.0");
91        assert!(!gh.install_url.is_empty());
92        assert!(!gh.doc_link.is_empty());
93    }
94
95    #[test]
96    fn test_should_return_gitcode_min_version_0_6() {
97        let gc = platform_requirement("gitcode").expect("gitcode should exist");
98        assert_eq!(gc.min_version, "0.6.0");
99    }
100
101    #[test]
102    fn test_should_return_none_for_unknown_platform() {
103        assert!(platform_requirement("bitbucket").is_none());
104    }
105}