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    /// gf 版本。
30    #[allow(
31        dead_code,
32        reason = "Deserialized for validation, not yet used at runtime"
33    )]
34    #[serde(rename = "gitflow_cli_version")]
35    gf_version: String,
36    /// 平台列表。
37    platforms: Vec<PlatformCompat>,
38}
39
40/// 单个平台的兼容性信息。
41#[derive(Debug, Clone, Deserialize)]
42pub struct PlatformCompat {
43    /// 平台显示名称(如 `"GitHub"`)。
44    pub name: String,
45    /// 平台标识符(如 `"github"`)。
46    pub identifier: String,
47    /// CLI 可执行文件名(如 `"gh"`)。
48    pub cli_binary: String,
49    /// 最低版本号(semver)。
50    pub min_version: String,
51    /// 已测试的版本列表。
52    pub tested_versions: Vec<String>,
53    /// 官方安装指引链接。
54    pub install_url: String,
55    /// 文档链接。
56    pub doc_link: String,
57}
58
59/// 获取所有平台的兼容性信息。
60///
61/// # Panics
62///
63/// 当嵌入的 JSON 格式无效时 panic(编译时数据损坏,属于不可恢复错误)。
64#[must_use]
65#[allow(
66    clippy::expect_used,
67    reason = "Embedded JSON is compile-time data; parse failure means corrupted build artifacts"
68)]
69pub fn platform_compatibility() -> Vec<PlatformCompat> {
70    let root: MatrixRoot =
71        serde_json::from_str(MATRIX_JSON).expect("embedded compatibility-matrix.json is invalid");
72    root.platforms
73}
74
75/// 获取指定平台的兼容性信息。
76#[must_use]
77pub fn platform_requirement(identifier: &str) -> Option<PlatformCompat> {
78    platform_compatibility()
79        .into_iter()
80        .find(|p| p.identifier == identifier)
81}
82
83#[cfg(test)]
84mod tests {
85    use super::*;
86
87    #[test]
88    fn test_should_load_all_three_platforms() {
89        let platforms = platform_compatibility();
90        assert_eq!(platforms.len(), 3);
91    }
92
93    #[test]
94    fn test_should_return_github_requirement() {
95        let gh = platform_requirement("github").expect("github should exist");
96        assert_eq!(gh.cli_binary, "gh");
97        assert_eq!(gh.min_version, "2.0.0");
98        assert!(!gh.install_url.is_empty());
99        assert!(!gh.doc_link.is_empty());
100    }
101
102    #[test]
103    fn test_should_return_gitcode_min_version_0_6() {
104        let gc = platform_requirement("gitcode").expect("gitcode should exist");
105        assert_eq!(gc.min_version, "0.6.0");
106    }
107
108    #[test]
109    fn test_should_return_none_for_unknown_platform() {
110        assert!(platform_requirement("bitbucket").is_none());
111    }
112}