Skip to main content

gitflow_github/
commit.rs

1//! GitHub Commit 提供者实现。
2//!
3//! 通过 `gh api` CLI 命令实现 [`CommitProvider`] trait,
4//! 支持 Commit 查看、Diff/Patch 获取及评论功能。
5
6use async_trait::async_trait;
7use gitflow_core::{
8    CoreError, Result,
9    commit::{CommitDetail, CommitFile, CommitProvider},
10    types::UserSummary,
11};
12use serde::Deserialize;
13use tracing::debug;
14
15use crate::error::parse_gh_error;
16
17/// GitHub Commit 提供者,通过 `gh api` 查看提交信息。
18///
19/// # Examples
20///
21/// ```no_run
22/// use gitflow_github::GitHubCommitProvider;
23///
24/// let provider = GitHubCommitProvider::new("octocat/hello-world");
25/// ```
26#[derive(Debug, Clone)]
27pub struct GitHubCommitProvider {
28    /// GitHub `owner/repo`。
29    repo: String,
30}
31
32impl GitHubCommitProvider {
33    /// 创建新的 GitHub Commit 提供者。
34    ///
35    /// `repo` 格式为 `owner/repo`。
36    #[must_use]
37    pub fn new(repo: impl Into<String>) -> Self {
38        Self { repo: repo.into() }
39    }
40
41    /// Create a new provider from a shared [`Session`].
42    ///
43    /// This enables state reuse across multiple operations in workflow chains.
44    #[must_use]
45    pub fn with_session(session: &gitflow_core::Session) -> Self {
46        Self {
47            repo: session.repo.clone(),
48        }
49    }
50}
51
52/// `gh api repos/<repo>/commits/<sha>` 返回的 JSON 结构。
53#[derive(Debug, Clone, Deserialize)]
54#[serde(rename_all = "camelCase")]
55#[allow(
56    dead_code,
57    reason = "Fields deserialized by serde but not all read directly"
58)]
59struct CommitApiResponse {
60    sha: String,
61    commit: CommitInner,
62    author: Option<ApiUser>,
63    committer: Option<ApiUser>,
64    #[serde(default)]
65    stats: Option<CommitStats>,
66    #[serde(default)]
67    files: Vec<CommitFileResponse>,
68}
69
70#[derive(Debug, Clone, Deserialize)]
71#[serde(rename_all = "camelCase")]
72#[allow(
73    dead_code,
74    reason = "Fields deserialized by serde but not all read directly"
75)]
76struct CommitInner {
77    message: String,
78    author: Option<CommitAuthorInner>,
79    committer: Option<CommitAuthorInner>,
80}
81
82#[derive(Debug, Clone, Deserialize)]
83#[serde(rename_all = "camelCase")]
84#[allow(
85    dead_code,
86    reason = "Fields deserialized by serde but not all read directly"
87)]
88struct CommitAuthorInner {
89    #[serde(default)]
90    date: Option<String>,
91}
92
93#[derive(Debug, Clone, Deserialize)]
94#[serde(rename_all = "camelCase")]
95#[allow(
96    dead_code,
97    reason = "Fields deserialized by serde but not all read directly"
98)]
99struct CommitStats {
100    #[serde(default)]
101    additions: u64,
102    #[serde(default)]
103    deletions: u64,
104    #[serde(default)]
105    total: u64,
106}
107
108#[derive(Debug, Clone, Deserialize)]
109#[serde(rename_all = "camelCase")]
110struct CommitFileResponse {
111    filename: String,
112    #[serde(default)]
113    additions: u64,
114    #[serde(default)]
115    deletions: u64,
116    #[serde(default)]
117    status: String,
118}
119
120/// GitHub API 返回的用户信息。
121#[derive(Debug, Clone, Deserialize)]
122#[serde(rename_all = "camelCase")]
123struct ApiUser {
124    login: String,
125    #[serde(
126        default,
127        deserialize_with = "gitflow_core::types::deserialize_u64_or_string_to_string"
128    )]
129    id: String,
130}
131
132impl From<&ApiUser> for UserSummary {
133    fn from(u: &ApiUser) -> Self {
134        Self {
135            login: u.login.clone(),
136            id: u.id.clone(),
137        }
138    }
139}
140
141/// 将 API 响应转换为 `CommitDetail`。
142impl From<CommitApiResponse> for CommitDetail {
143    fn from(api: CommitApiResponse) -> Self {
144        let author = api.author.as_ref().map_or_else(
145            || fallback_user(api.commit.author.as_ref()),
146            UserSummary::from,
147        );
148        let committer = api.committer.as_ref().map_or_else(
149            || fallback_user(api.commit.committer.as_ref()),
150            UserSummary::from,
151        );
152
153        let files: Vec<CommitFile> = api
154            .files
155            .into_iter()
156            .map(|f| CommitFile {
157                filename: f.filename,
158                additions: f.additions,
159                deletions: f.deletions,
160                status: f.status,
161            })
162            .collect();
163
164        Self {
165            sha: api.sha,
166            message: api.commit.message,
167            author,
168            committer,
169            diff: None,
170            files,
171        }
172    }
173}
174
175/// 为 `CommitData` 构造后备用户(当 API 未返回用户信息时)。
176fn fallback_user(_inner: Option<&CommitAuthorInner>) -> UserSummary {
177    UserSummary {
178        login: "unknown".into(),
179        id: "0".to_string(),
180    }
181}
182
183#[async_trait]
184impl CommitProvider for GitHubCommitProvider {
185    async fn view(&self, sha: &str) -> Result<CommitDetail> {
186        debug!(repo = %self.repo, sha, "spawning `gh api commit view`");
187
188        let api_path = format!("repos/{repo}/commits/{sha}", repo = self.repo);
189
190        let output = tokio::process::Command::new("gh")
191            .args(["api", &api_path])
192            .output()
193            .await
194            .map_err(|e| CoreError::Platform(format!("Failed to spawn gh api commit view: {e}")))?;
195
196        if !output.status.success() {
197            return Err(parse_gh_error(&output.stderr).into());
198        }
199
200        let api_response: CommitApiResponse =
201            serde_json::from_slice(&output.stdout).map_err(CoreError::Serialization)?;
202
203        Ok(api_response.into())
204    }
205
206    async fn diff(&self, sha: &str) -> Result<String> {
207        debug!(repo = %self.repo, sha, "spawning `gh api commit diff`");
208
209        let api_path = format!("repos/{repo}/commits/{sha}", repo = self.repo);
210
211        let output = tokio::process::Command::new("gh")
212            .args(["api", &api_path])
213            .arg("-H")
214            .arg("Accept: application/vnd.github.v3.diff")
215            .output()
216            .await
217            .map_err(|e| CoreError::Platform(format!("Failed to spawn gh api commit diff: {e}")))?;
218
219        if !output.status.success() {
220            return Err(parse_gh_error(&output.stderr).into());
221        }
222
223        Ok(String::from_utf8_lossy(&output.stdout).into_owned())
224    }
225
226    async fn patch(&self, sha: &str) -> Result<String> {
227        debug!(repo = %self.repo, sha, "spawning `gh api commit patch`");
228
229        let api_path = format!("repos/{repo}/commits/{sha}", repo = self.repo);
230
231        let output = tokio::process::Command::new("gh")
232            .args(["api", &api_path])
233            .arg("-H")
234            .arg("Accept: application/vnd.github.v3.patch")
235            .output()
236            .await
237            .map_err(|e| {
238                CoreError::Platform(format!("Failed to spawn gh api commit patch: {e}"))
239            })?;
240
241        if !output.status.success() {
242            return Err(parse_gh_error(&output.stderr).into());
243        }
244
245        Ok(String::from_utf8_lossy(&output.stdout).into_owned())
246    }
247
248    async fn comment(&self, sha: &str, body: &str, path: &str, line: u64) -> Result<()> {
249        debug!(repo = %self.repo, sha, "spawning `gh api commit comment`");
250
251        let api_path = format!("repos/{repo}/commits/{sha}/comments", repo = self.repo);
252
253        let mut cmd = tokio::process::Command::new("gh");
254        cmd.args(["api", &api_path, "-X", "POST"])
255            .arg("-f")
256            .arg(format!("body={body}"))
257            .arg("-f")
258            .arg(format!("path={path}"))
259            .arg("-f")
260            .arg(format!("line={line}"))
261            .arg("-f")
262            .arg("position=1");
263
264        let output = cmd.output().await.map_err(|e| {
265            CoreError::Platform(format!("Failed to spawn gh api commit comment: {e}"))
266        })?;
267
268        if !output.status.success() {
269            return Err(parse_gh_error(&output.stderr).into());
270        }
271
272        Ok(())
273    }
274}
275
276#[cfg(test)]
277mod tests {
278    use super::*;
279
280    // --- GitHubCommitProvider tests ---
281
282    #[test]
283    fn test_should_construct_github_commit_provider() {
284        let provider = GitHubCommitProvider::new("octocat/hello-world");
285        assert_eq!(provider.repo, "octocat/hello-world");
286    }
287
288    #[test]
289    fn test_should_construct_github_commit_provider_from_string() {
290        let repo = String::from("octocat/hello-world");
291        let provider = GitHubCommitProvider::new(repo);
292        assert_eq!(provider.repo, "octocat/hello-world");
293    }
294
295    #[test]
296    fn test_should_debug_format_commit_provider() {
297        let provider = GitHubCommitProvider::new("owner/repo");
298        let debug = format!("{provider:?}");
299        assert!(debug.contains("GitHubCommitProvider"));
300        assert!(debug.contains("owner/repo"));
301    }
302
303    #[test]
304    fn test_should_clone_github_commit_provider() {
305        let original = GitHubCommitProvider::new("owner/repo");
306        let cloned = original.clone();
307        assert_eq!(original.repo, cloned.repo);
308    }
309
310    // --- API response deserialization tests ---
311
312    #[test]
313    fn test_should_deserialize_commit_api_response() {
314        let json = br#"{
315            "sha": "abc123def456",
316            "commit": {
317                "message": "Fix login bug\n\nMore details here.",
318                "author": {"date": "2026-01-15T09:30:00Z"},
319                "committer": {"date": "2026-01-15T09:30:00Z"}
320            },
321            "author": {"login": "alice", "id": "7"},
322            "committer": {"login": "bob", "id": "12"},
323            "stats": {"additions": 15, "deletions": 3, "total": 18},
324            "files": [
325                {"filename": "auth.rs", "additions": 10, "deletions": 0, "status": "modified"},
326                {"filename": "tests/auth.rs", "additions": 5, "deletions": 3, "status": "modified"}
327            ]
328        }"#;
329
330        let api: CommitApiResponse = serde_json::from_slice(json).expect("valid CommitApiResponse");
331        assert_eq!(api.sha, "abc123def456");
332        assert!(api.commit.message.contains("Fix login bug"));
333        assert_eq!(api.author.as_ref().map(|u| &*u.login), Some("alice"));
334        assert_eq!(api.files.len(), 2);
335        assert_eq!(api.files[0].filename, "auth.rs");
336        assert_eq!(api.stats.as_ref().map(|s| s.additions), Some(15));
337    }
338
339    #[test]
340    fn test_should_deserialize_commit_detail_from_api() {
341        let json = br#"{
342            "sha": "deadbeef",
343            "commit": {
344                "message": "Add feature",
345                "author": null,
346                "committer": null
347            },
348            "author": null,
349            "committer": null,
350            "stats": null,
351            "files": []
352        }"#;
353
354        let api: CommitApiResponse = serde_json::from_slice(json).expect("valid CommitApiResponse");
355        let detail: CommitDetail = api.into();
356
357        assert_eq!(detail.sha, "deadbeef");
358        assert_eq!(detail.message, "Add feature");
359        assert_eq!(detail.author.login, "unknown");
360        assert!(detail.diff.is_none());
361        assert!(detail.files.is_empty());
362    }
363
364    #[test]
365    fn test_should_deserialize_commit_file_response() {
366        let json = br#"{"filename":"src/main.rs","additions":5,"deletions":2,"status":"modified"}"#;
367
368        let file: CommitFileResponse =
369            serde_json::from_slice(json).expect("valid CommitFileResponse");
370        assert_eq!(file.filename, "src/main.rs");
371        assert_eq!(file.additions, 5);
372        assert_eq!(file.deletions, 2);
373        assert_eq!(file.status, "modified");
374    }
375
376    #[test]
377    fn test_should_deserialize_api_user() {
378        let json = br#"{"login":"octocat","id":"583231"}"#;
379        let user: ApiUser = serde_json::from_slice(json).expect("valid ApiUser");
380        assert_eq!(user.login, "octocat");
381        assert_eq!(user.id, "583231");
382    }
383
384    #[test]
385    fn test_should_convert_api_user_to_user_summary() {
386        let user = ApiUser {
387            login: "alice".into(),
388            id: "42".to_string(),
389        };
390        let summary: UserSummary = (&user).into();
391        assert_eq!(summary.login, "alice");
392        assert_eq!(summary.id, "42");
393    }
394
395    #[test]
396    fn test_should_convert_commit_api_to_detail() {
397        let api = CommitApiResponse {
398            sha: "sha123".into(),
399            commit: CommitInner {
400                message: "Test commit".into(),
401                author: None,
402                committer: None,
403            },
404            author: Some(ApiUser {
405                login: "dev".into(),
406                id: "1".to_string(),
407            }),
408            committer: Some(ApiUser {
409                login: "dev".into(),
410                id: "1".to_string(),
411            }),
412            stats: Some(CommitStats {
413                additions: 10,
414                deletions: 2,
415                total: 12,
416            }),
417            files: vec![CommitFileResponse {
418                filename: "lib.rs".into(),
419                additions: 10,
420                deletions: 2,
421                status: "modified".into(),
422            }],
423        };
424
425        let detail: CommitDetail = api.into();
426        assert_eq!(detail.sha, "sha123");
427        assert_eq!(detail.message, "Test commit");
428        assert_eq!(detail.author.login, "dev");
429        assert_eq!(detail.files.len(), 1);
430        assert_eq!(detail.files[0].filename, "lib.rs");
431    }
432
433    #[test]
434    fn test_should_fallback_user_when_api_returns_no_user_info() {
435        let summary = fallback_user(None);
436        assert_eq!(summary.login, "unknown");
437        assert_eq!(summary.id, "0");
438    }
439
440    #[test]
441    fn test_should_convert_commit_api_to_detail_with_mixed_author_committer() {
442        // author present, committer absent -> committer should fallback to unknown
443        let api = CommitApiResponse {
444            sha: "sha_mixed".into(),
445            commit: CommitInner {
446                message: "Mixed authors".into(),
447                author: None,
448                committer: None,
449            },
450            author: Some(ApiUser {
451                login: "author_only".into(),
452                id: "10".to_string(),
453            }),
454            committer: None,
455            stats: None,
456            files: vec![],
457        };
458
459        let detail: CommitDetail = api.into();
460        assert_eq!(detail.author.login, "author_only");
461        assert_eq!(detail.committer.login, "unknown");
462
463        // committer present, author absent -> author should fallback to unknown
464        let api2 = CommitApiResponse {
465            sha: "sha_mixed2".into(),
466            commit: CommitInner {
467                message: "Mixed authors 2".into(),
468                author: None,
469                committer: None,
470            },
471            author: None,
472            committer: Some(ApiUser {
473                login: "committer_only".into(),
474                id: "20".to_string(),
475            }),
476            stats: None,
477            files: vec![],
478        };
479
480        let detail2: CommitDetail = api2.into();
481        assert_eq!(detail2.author.login, "unknown");
482        assert_eq!(detail2.committer.login, "committer_only");
483    }
484}