Skip to main content

orch/github/
types.rs

1//! GitHub API response types — deserialized from `gh api` JSON output.
2
3use serde::{Deserialize, Serialize};
4
5#[derive(Debug, Clone, Serialize, Deserialize)]
6pub struct GitHubIssue {
7    pub number: u64,
8    /// GitHub database id, the value the dependencies API calls issue_id
9    #[serde(default)]
10    pub id: u64,
11    pub title: String,
12    pub body: Option<String>,
13    pub state: String,
14    pub labels: Vec<GitHubLabel>,
15    pub user: GitHubUser,
16    pub created_at: String,
17    pub updated_at: String,
18    pub html_url: String,
19    pub node_id: Option<String>,
20    /// Present when the item is actually a pull request (GitHub API returns PRs in /issues).
21    pub pull_request: Option<serde_json::Value>,
22    /// Author's relationship to the repo: OWNER, MEMBER, COLLABORATOR, CONTRIBUTOR,
23    /// FIRST_TIME_CONTRIBUTOR, FIRST_TIMER, MANNEQUIN, NONE.
24    #[serde(default)]
25    pub author_association: Option<String>,
26    /// `completed`, `not_planned`, `duplicate`, `reopened`, or absent
27    #[serde(default)]
28    pub state_reason: Option<String>,
29}
30
31#[derive(Debug, Clone, Serialize, Deserialize)]
32pub struct GitHubLabel {
33    pub name: String,
34    pub color: Option<String>,
35}
36
37#[derive(Debug, Clone, Serialize, Deserialize)]
38pub struct GitHubUser {
39    pub login: String,
40}
41
42/// Pull request details from the GitHub API.
43/// The `mergeable` field indicates if the PR can be merged:
44/// - `true` - PR can be merged
45/// - `false` - PR has merge conflicts (CONFLICTING)
46/// - `null` - GitHub is still computing mergeability
47#[derive(Debug, Clone, Serialize, Deserialize)]
48pub struct GitHubPullRequest {
49    pub number: u64,
50    pub title: String,
51    pub body: Option<String>,
52    pub state: String,
53    pub head: GitHubBranchRef,
54    pub base: GitHubBranchRef,
55    pub mergeable: Option<bool>,
56    pub mergeable_state: Option<String>,
57    pub merged: Option<bool>,
58    pub html_url: String,
59}
60
61#[derive(Debug, Clone, Serialize, Deserialize)]
62pub struct GitHubCheckRun {
63    pub id: u64,
64    pub name: String,
65    pub status: String,
66    pub conclusion: Option<String>,
67    /// GitHub App that posted the run, used to match a ruleset `integration_id`
68    #[serde(default)]
69    pub app: Option<GitHubApp>,
70}
71
72impl GitHubCheckRun {
73    pub(crate) fn is_finished(&self) -> bool {
74        check_run_is_finished(&self.status, self.conclusion.as_deref())
75    }
76
77    pub(crate) fn is_passed(&self) -> bool {
78        check_conclusion_passed(self.conclusion.as_deref())
79    }
80}
81
82/// `action_required` is completed on GitHub but still needs a person
83pub(crate) fn check_run_is_finished(status: &str, conclusion: Option<&str>) -> bool {
84    status == "completed" && conclusion.is_some_and(|c| c != "action_required")
85}
86
87pub(crate) fn check_conclusion_passed(conclusion: Option<&str>) -> bool {
88    matches!(conclusion, Some("success" | "neutral" | "skipped"))
89}
90
91/// The GitHub App that created a check run (`check_run.app`)
92#[derive(Debug, Clone, Serialize, Deserialize)]
93pub struct GitHubApp {
94    pub id: i64,
95}
96
97/// A required status check from classic branch protection or a ruleset
98#[derive(Debug, Clone, PartialEq, Eq, Hash)]
99pub struct RequiredStatusCheck {
100    pub context: String,
101    /// GitHub App that must post this check. `None` means any app's check with this name counts
102    pub integration_id: Option<i64>,
103}
104
105/// A check run annotation returned by the GitHub Checks API.
106///
107/// Annotations appear on the "Annotations" tab of a check run in the GitHub UI.
108/// GitHub uses annotations for job-level messages, including billing failures
109/// ("The job was not started because recent account payments have failed …").
110#[derive(Debug, Clone, Serialize, Deserialize)]
111pub struct GitHubAnnotation {
112    pub annotation_level: Option<String>,
113    pub message: Option<String>,
114    pub title: Option<String>,
115}
116
117#[derive(Debug, Clone, Serialize, Deserialize)]
118pub struct GitHubBranchRef {
119    #[serde(rename = "ref")]
120    pub ref_: String,
121    pub sha: String,
122    /// The repository the branch lives in, a fork when the PR comes from one
123    #[serde(default)]
124    pub repo: Option<GitHubRepoRef>,
125}
126
127#[derive(Debug, Clone, Serialize, Deserialize)]
128pub struct GitHubRepoRef {
129    pub full_name: String,
130}
131
132#[derive(Debug, Clone, Serialize, Deserialize)]
133pub struct GitHubComment {
134    pub id: u64,
135    pub body: String,
136    pub user: GitHubUser,
137    pub created_at: String,
138    pub updated_at: Option<String>,
139    pub html_url: Option<String>,
140    /// Present when fetched from the repo-level /issues/comments endpoint.
141    /// Format: https://api.github.com/repos/owner/repo/issues/123
142    pub issue_url: Option<String>,
143    /// Author's relationship to the repo for comment payloads when present.
144    /// This field is present on repo-level comment endpoints and may be
145    /// missing for some GraphQL-derived nodes. See `author_association` on
146    /// issues for the corresponding field.
147    #[serde(default)]
148    pub author_association: Option<String>,
149}
150
151/// Extract issue/PR number from a GitHub API URL.
152///
153/// Parses the trailing numeric segment from URLs like:
154/// `https://api.github.com/repos/owner/repo/issues/123`
155pub fn extract_issue_number_from_url(url: &str) -> Option<String> {
156    url.rsplit('/')
157        .next()
158        .filter(|s| !s.is_empty() && s.chars().all(|c| c.is_ascii_digit()))
159        .map(String::from)
160}
161
162/// PR review state - "APPROVED", "CHANGES_REQUESTED", "COMMENTED", "DISMISSED"
163#[derive(Debug, Clone, Serialize, Deserialize)]
164pub struct GitHubReview {
165    pub id: u64,
166    pub user: GitHubUser,
167    pub body: Option<String>,
168    pub state: String,
169    pub html_url: Option<String>,
170    pub submitted_at: String,
171    pub commit_id: Option<String>,
172}
173
174/// PR review comment on a specific line of code.
175#[derive(Debug, Clone, Serialize, Deserialize)]
176pub struct GitHubReviewComment {
177    pub id: u64,
178    pub user: GitHubUser,
179    pub body: String,
180    pub path: String,
181    pub line: Option<u32>,
182    pub original_line: Option<u32>,
183    pub commit_id: String,
184    pub original_commit_id: String,
185    pub html_url: String,
186    pub created_at: String,
187    pub updated_at: String,
188    pub in_reply_to_id: Option<u64>,
189    pub diff_hunk: Option<String>,
190}
191
192/// A PR review with its associated comments.
193#[derive(Debug, Clone)]
194pub struct PullRequestReview {
195    pub review: GitHubReview,
196    pub comments: Vec<GitHubReviewComment>,
197}
198
199impl PullRequestReview {
200    /// Get actionable comments (non-empty, not replies).
201    pub fn actionable_comments(&self) -> Vec<&GitHubReviewComment> {
202        self.comments
203            .iter()
204            .filter(|c| !c.body.trim().is_empty() && c.in_reply_to_id.is_none())
205            .collect()
206    }
207}
208
209#[cfg(test)]
210impl PullRequestReview {
211    /// Check if this review requests changes (test helper).
212    pub fn requests_changes(&self) -> bool {
213        self.review.state == "CHANGES_REQUESTED"
214    }
215}
216
217#[cfg(test)]
218mod tests {
219    use super::*;
220
221    #[test]
222    fn action_required_is_not_finished() {
223        assert!(!check_run_is_finished("completed", Some("action_required")));
224        assert!(check_run_is_finished("completed", Some("success")));
225        assert!(check_run_is_finished("completed", Some("failure")));
226        assert!(check_run_is_finished("completed", Some("skipped")));
227        assert!(!check_run_is_finished("completed", None));
228        assert!(!check_run_is_finished("in_progress", None));
229        assert!(!check_run_is_finished("waiting", None));
230        assert!(!check_conclusion_passed(Some("action_required")));
231        assert!(check_conclusion_passed(Some("success")));
232        assert!(check_conclusion_passed(Some("skipped")));
233        assert!(!check_conclusion_passed(Some("failure")));
234    }
235
236    #[test]
237    fn test_github_review_deserialization() {
238        let json = r#"{
239            "id": 789,
240            "user": {"login": "reviewer"},
241            "body": "Please fix this",
242            "state": "CHANGES_REQUESTED",
243            "html_url": "https://github.com/test/repo/pull/123#pullrequestreview-789",
244            "submitted_at": "2024-01-01T12:00:00Z",
245            "commit_id": "abc123"
246        }"#;
247
248        let review: GitHubReview = serde_json::from_str(json).unwrap();
249        assert_eq!(review.id, 789);
250        assert_eq!(review.user.login, "reviewer");
251        assert_eq!(review.body, Some("Please fix this".to_string()));
252        assert_eq!(review.state, "CHANGES_REQUESTED");
253        assert_eq!(review.submitted_at, "2024-01-01T12:00:00Z");
254        assert_eq!(review.commit_id, Some("abc123".to_string()));
255    }
256
257    #[test]
258    fn test_github_review_comment_deserialization() {
259        let json = r#"{
260            "id": 101112,
261            "user": {"login": "reviewer"},
262            "body": "This line needs fixing",
263            "path": "src/main.rs",
264            "line": 42,
265            "original_line": 42,
266            "commit_id": "abc123",
267            "original_commit_id": "abc123",
268            "html_url": "https://github.com/test/repo/pull/123#discussion_r101112",
269            "created_at": "2024-01-01T12:00:00Z",
270            "updated_at": "2024-01-01T12:00:00Z",
271            "in_reply_to_id": null,
272            "diff_hunk": "@@ -40,5 +40,5 @@ fn main() {\n     let x = 1;\n-    let y = 2;\n+    let y = 3;"
273        }"#;
274
275        let comment: GitHubReviewComment = serde_json::from_str(json).unwrap();
276        assert_eq!(comment.id, 101_112);
277        assert_eq!(comment.user.login, "reviewer");
278        assert_eq!(comment.body, "This line needs fixing");
279        assert_eq!(comment.path, "src/main.rs");
280        assert_eq!(comment.line, Some(42));
281        assert_eq!(comment.commit_id, "abc123");
282        assert_eq!(comment.in_reply_to_id, None);
283        assert!(comment.diff_hunk.is_some());
284    }
285
286    #[test]
287    fn github_check_run_deserializes_app_id() {
288        let json = r#"{
289            "id": 4,
290            "name": "ci/test",
291            "status": "completed",
292            "conclusion": "success",
293            "app": { "id": 42, "slug": "shipcheck", "name": "shipcheck" }
294        }"#;
295        let run: GitHubCheckRun = serde_json::from_str(json).unwrap();
296        assert_eq!(run.name, "ci/test");
297        assert_eq!(run.app.unwrap().id, 42);
298    }
299
300    #[test]
301    fn github_check_run_deserializes_without_app() {
302        let json = r#"{
303            "id": 4,
304            "name": "ci/test",
305            "status": "completed",
306            "conclusion": "success"
307        }"#;
308        let run: GitHubCheckRun = serde_json::from_str(json).unwrap();
309        assert!(run.app.is_none());
310    }
311
312    #[test]
313    fn test_github_branch_ref_deserialization() {
314        let json = r#"{
315            "ref": "main",
316            "sha": "abc123"
317        }"#;
318
319        let branch_ref: GitHubBranchRef = serde_json::from_str(json).unwrap();
320        assert_eq!(branch_ref.ref_, "main");
321        assert_eq!(branch_ref.sha, "abc123");
322    }
323
324    #[test]
325    fn test_pull_request_review_requests_changes() {
326        let review = PullRequestReview {
327            review: GitHubReview {
328                id: 1,
329                user: GitHubUser {
330                    login: "reviewer".to_string(),
331                },
332                body: Some("Please fix".to_string()),
333                state: "CHANGES_REQUESTED".to_string(),
334                html_url: None,
335                submitted_at: "2024-01-01T00:00:00Z".to_string(),
336                commit_id: None,
337            },
338            comments: vec![],
339        };
340
341        assert!(review.requests_changes());
342    }
343
344    #[test]
345    fn test_pull_request_review_approved() {
346        let review = PullRequestReview {
347            review: GitHubReview {
348                id: 1,
349                user: GitHubUser {
350                    login: "reviewer".to_string(),
351                },
352                body: Some("LGTM".to_string()),
353                state: "APPROVED".to_string(),
354                html_url: None,
355                submitted_at: "2024-01-01T00:00:00Z".to_string(),
356                commit_id: None,
357            },
358            comments: vec![],
359        };
360
361        assert!(!review.requests_changes());
362    }
363
364    #[test]
365    fn test_pull_request_review_actionable_comments() {
366        let review = PullRequestReview {
367            review: GitHubReview {
368                id: 1,
369                user: GitHubUser {
370                    login: "reviewer".to_string(),
371                },
372                body: None,
373                state: "CHANGES_REQUESTED".to_string(),
374                html_url: None,
375                submitted_at: "2024-01-01T00:00:00Z".to_string(),
376                commit_id: None,
377            },
378            comments: vec![
379                GitHubReviewComment {
380                    id: 1,
381                    user: GitHubUser {
382                        login: "reviewer".to_string(),
383                    },
384                    body: "Fix this".to_string(),
385                    path: "src/main.rs".to_string(),
386                    line: Some(10),
387                    original_line: Some(10),
388                    commit_id: "abc".to_string(),
389                    original_commit_id: "abc".to_string(),
390                    html_url: "url".to_string(),
391                    created_at: "2024-01-01T00:00:00Z".to_string(),
392                    updated_at: "2024-01-01T00:00:00Z".to_string(),
393                    in_reply_to_id: None,
394                    diff_hunk: None,
395                },
396                GitHubReviewComment {
397                    id: 2,
398                    user: GitHubUser {
399                        login: "reviewer".to_string(),
400                    },
401                    body: String::new(), // Empty - not actionable
402                    path: "src/lib.rs".to_string(),
403                    line: Some(20),
404                    original_line: Some(20),
405                    commit_id: "abc".to_string(),
406                    original_commit_id: "abc".to_string(),
407                    html_url: "url".to_string(),
408                    created_at: "2024-01-01T00:00:00Z".to_string(),
409                    updated_at: "2024-01-01T00:00:00Z".to_string(),
410                    in_reply_to_id: None,
411                    diff_hunk: None,
412                },
413                GitHubReviewComment {
414                    id: 3,
415                    user: GitHubUser {
416                        login: "reviewer".to_string(),
417                    },
418                    body: "Reply to this".to_string(),
419                    path: "src/lib.rs".to_string(),
420                    line: Some(30),
421                    original_line: Some(30),
422                    commit_id: "abc".to_string(),
423                    original_commit_id: "abc".to_string(),
424                    html_url: "url".to_string(),
425                    created_at: "2024-01-01T00:00:00Z".to_string(),
426                    updated_at: "2024-01-01T00:00:00Z".to_string(),
427                    in_reply_to_id: Some(1), // Reply - not actionable as standalone
428                    diff_hunk: None,
429                },
430            ],
431        };
432
433        let actionable = review.actionable_comments();
434        assert_eq!(actionable.len(), 1);
435        assert_eq!(actionable[0].id, 1);
436        assert_eq!(actionable[0].body, "Fix this");
437    }
438
439    #[test]
440    fn extract_issue_number_from_url_works() {
441        assert_eq!(
442            extract_issue_number_from_url("https://api.github.com/repos/owner/repo/issues/123"),
443            Some("123".into())
444        );
445    }
446
447    #[test]
448    fn extract_issue_number_from_url_empty() {
449        assert_eq!(extract_issue_number_from_url(""), None);
450    }
451}