Skip to main content

jouet_github/
gitlab.rs

1//! GitLab merge requests behind [`Host`], through the REST API (v4).
2//!
3//! An MR's status is read from the MR itself (its `detailed_merge_status`
4//! gives mergeability and what blocks it), its approvals, its discussions
5//! and the commit statuses of its head, which hold the pipeline's jobs and
6//! any external statuses. A review thread is a resolvable discussion: its
7//! ID is its first note's, its handle for replies and resolving is the
8//! discussion's own ID.
9
10use crate::forge::Forge;
11use crate::host::{Feature, Host};
12use crate::pr::status::{Checks, FetchResult, Fetched, Lookup, Mergeability, PrStatus, State};
13use crate::pr::target::{Repo, Target};
14use crate::pr::threads::{self, Activity, Comment, Kind, PrThreads, Pushed, Side, Thread};
15use crate::rest::{Rest, encode, utc};
16use crate::{Failure, Method};
17use jouet_output::time;
18use serde_json::{Value, json};
19
20pub struct GitLab {
21    rest: Rest,
22}
23
24impl GitLab {
25    pub fn new(host: &str) -> Self {
26        Self {
27            rest: Rest::new(Forge::GitLab, host),
28        }
29    }
30
31    /// The REST client, for the CI reads `wait` makes.
32    pub fn rest(&mut self) -> &mut Rest {
33        &mut self.rest
34    }
35
36    /// The MR a target names: a number as is, a branch through its open MR,
37    /// else its newest. `None` when there is none.
38    pub fn number(&mut self, target: &Target) -> Result<Option<u64>, Failure> {
39        let (repo, branch) = match target {
40            Target::Number(_, n) => return Ok(Some(*n)),
41            Target::Branch(repo, branch) => (repo, branch),
42        };
43        for state in ["&state=opened", ""] {
44            let path = format!(
45                "{}/merge_requests?source_branch={}{state}&order_by=created_at&sort=desc&per_page=1",
46                project(repo),
47                encode(branch)
48            );
49            if let Some(Value::Array(mrs)) = self.rest.json(&path)?
50                && let Some(n) = mrs.first().and_then(|m| m["iid"].as_u64())
51            {
52                return Ok(Some(n));
53            }
54        }
55        Ok(None)
56    }
57
58    fn mr(&mut self, repo: &Repo, n: u64) -> Result<Option<Value>, Failure> {
59        self.rest.json(&format!(
60            "{}/merge_requests/{n}?with_merge_status_recheck=true",
61            project(repo)
62        ))
63    }
64
65    /// An MR's status, as `pr status` reports a PR.
66    fn status(&mut self, repo: &Repo, mr: &Value) -> Result<Fetched, Failure> {
67        let base = project(repo);
68        let n = mr["iid"].as_u64().unwrap_or_default();
69        let state = match mr["state"].as_str() {
70            Some("merged") => State::Merged,
71            Some("closed" | "locked") => State::Closed,
72            _ if mr["draft"].as_bool() == Some(true)
73                || mr["work_in_progress"].as_bool() == Some(true) =>
74            {
75                State::Draft
76            }
77            _ => State::Open,
78        };
79        let detailed = mr["detailed_merge_status"]
80            .as_str()
81            .or(mr["merge_status"].as_str())
82            .unwrap_or("unchecked");
83        let (mergeable, merge_state) = merge_state(detailed, mr["has_conflicts"].as_bool());
84        let head_oid = mr["sha"].as_str().unwrap_or_default().to_string();
85        let approvals = self
86            .rest
87            .json(&format!("{base}/merge_requests/{n}/approvals"))
88            .unwrap_or(None);
89        let review = if detailed == "requested_changes" {
90            Some("changes_requested".to_string())
91        } else {
92            approvals.as_ref().and_then(review)
93        };
94        let discussions = self
95            .rest
96            .list(&format!(
97                "{base}/merge_requests/{n}/discussions?per_page=100"
98            ))?
99            .unwrap_or_default();
100        let unresolved = discussions.iter().filter(|d| unresolved(d)).count();
101        let mut checks = Checks::default();
102        if !head_oid.is_empty() {
103            for s in statuses(&mut self.rest, repo, &head_oid)? {
104                let name = s["name"].as_str().unwrap_or_default().to_string();
105                match bucket(&s) {
106                    Bucket::Pass => checks.pass += 1,
107                    Bucket::Fail => {
108                        checks.fail += 1;
109                        checks.failing.push(name);
110                    }
111                    Bucket::Pending => checks.pending += 1,
112                    Bucket::Skipped => checks.skipped += 1,
113                }
114            }
115        }
116        let pushed_at = self
117            .rest
118            .list(&format!("{base}/merge_requests/{n}/versions?per_page=1"))
119            .ok()
120            .flatten()
121            .and_then(|v| utc(&v.first()?["created_at"]));
122        Ok(Fetched::new(PrStatus {
123            repo: repo.to_string(),
124            number: n,
125            title: mr["title"].as_str().unwrap_or_default().to_string(),
126            url: mr["web_url"].as_str().unwrap_or_default().to_string(),
127            state,
128            base: mr["target_branch"].as_str().unwrap_or_default().to_string(),
129            head: mr["source_branch"].as_str().unwrap_or_default().to_string(),
130            head_sha: head_oid.chars().take(10).collect(),
131            head_oid,
132            forge: Some("gitlab"),
133            host: repo.host.clone(),
134            pushed_at,
135            mergeable,
136            merge_state: merge_state.to_string(),
137            checks,
138            review,
139            unresolved_threads: u32::try_from(unresolved).unwrap_or(u32::MAX),
140            auto_merge: mr["merge_when_pipeline_succeeds"].as_bool() == Some(true)
141                || mr["auto_merge_enabled"].as_bool() == Some(true),
142            // Entire Gates is a GitHub check run.
143            entire: None,
144            attention: Vec::new(),
145        }))
146    }
147
148    /// The MR's commits, oldest first, with their commit times.
149    fn commits(&mut self, pr: &PrThreads) -> Result<Vec<(String, i64)>, String> {
150        let list = self
151            .rest
152            .list(&format!(
153                "{}/merge_requests/{}/commits?per_page=100",
154                project(&pr.repo),
155                pr.number
156            ))?
157            .unwrap_or_default();
158        let mut out: Vec<(String, i64)> = list
159            .iter()
160            .map(|c| {
161                let oid = c["id"].as_str().unwrap_or_default().to_string();
162                let at = c["committed_date"]
163                    .as_str()
164                    .and_then(time::parse_rfc3339)
165                    .unwrap_or(0);
166                (oid, at)
167            })
168            .collect();
169        out.reverse();
170        Ok(out)
171    }
172}
173
174/// `/projects/GROUP%2FSUB%2FNAME`.
175pub fn project(repo: &Repo) -> String {
176    format!("/projects/{}", encode(&repo.to_string()))
177}
178
179/// Mergeability and a GitHub-style merge state from GitLab's
180/// `detailed_merge_status`.
181fn merge_state(detailed: &str, has_conflicts: Option<bool>) -> (Mergeability, &'static str) {
182    let clean = if has_conflicts == Some(true) {
183        Mergeability::Conflicting
184    } else {
185        Mergeability::Mergeable
186    };
187    match detailed {
188        "mergeable" | "can_be_merged" => (Mergeability::Mergeable, "clean"),
189        "conflict" | "broken_status" | "cannot_be_merged" => (Mergeability::Conflicting, "dirty"),
190        "need_rebase" => (clean, "behind"),
191        "draft_status" => (clean, "draft"),
192        "checking"
193        | "unchecked"
194        | "preparing"
195        | "approvals_syncing"
196        | "cannot_be_merged_recheck" => (Mergeability::Unknown, "unknown"),
197        _ => (clean, "blocked"),
198    }
199}
200
201/// `approved` once nothing more is required and someone approved,
202/// `review_required` while approvals are still needed.
203fn review(approvals: &Value) -> Option<String> {
204    let left = approvals["approvals_left"].as_u64().unwrap_or(0);
205    let approved_by = approvals["approved_by"]
206        .as_array()
207        .is_some_and(|a| !a.is_empty());
208    if left > 0 {
209        Some("review_required".into())
210    } else if approved_by {
211        Some("approved".into())
212    } else {
213        None
214    }
215}
216
217/// A resolvable discussion with a note still unresolved.
218fn unresolved(discussion: &Value) -> bool {
219    let notes = discussion["notes"].as_array().cloned().unwrap_or_default();
220    notes
221        .iter()
222        .any(|n| n["resolvable"].as_bool() == Some(true) && n["resolved"].as_bool() != Some(true))
223}
224
225#[derive(Debug, Clone, Copy, PartialEq, Eq)]
226enum Bucket {
227    Pass,
228    Fail,
229    Pending,
230    Skipped,
231}
232
233/// How a commit status (a job or an external status) counts. A job allowed
234/// to fail passes with a warning, as GitLab shows it.
235fn bucket(s: &Value) -> Bucket {
236    match s["status"].as_str().unwrap_or_default() {
237        "success" => Bucket::Pass,
238        "failed" if s["allow_failure"].as_bool() == Some(true) => Bucket::Skipped,
239        "failed" | "canceled" | "canceling" => Bucket::Fail,
240        "skipped" | "manual" => Bucket::Skipped,
241        _ => Bucket::Pending,
242    }
243}
244
245/// The latest commit status of each name on `sha`: the jobs of its
246/// pipelines and any external statuses.
247pub fn statuses(rest: &mut Rest, repo: &Repo, sha: &str) -> Result<Vec<Value>, Failure> {
248    Ok(rest
249        .list(&format!(
250            "{}/repository/commits/{sha}/statuses?per_page=100",
251            project(repo)
252        ))?
253        .unwrap_or_default())
254}
255
256impl Host for GitLab {
257    fn forge(&self) -> Forge {
258        Forge::GitLab
259    }
260
261    fn lacks(&mut self, feature: Feature) -> Option<String> {
262        match feature {
263            Feature::Search => Some(
264                "--search takes GitHub's search syntax, which GitLab has no equivalent of".into(),
265            ),
266            Feature::Explain => Some(
267                "`ci explain` judges a failure by GitHub Actions' run history; GitLab pipelines have no equivalent jouet reads yet, so use `jouet wait ci` for the failed jobs and their logs".into(),
268            ),
269            Feature::Land => Some(
270                "`pr land` merges GitHub PRs only so far; merge the MR with `glab mr merge` or on the web".into(),
271            ),
272            Feature::Resolve | Feature::Runs | Feature::RequiredChecks => None,
273        }
274    }
275
276    fn fetch(&mut self, lookups: Vec<Lookup>) -> Result<FetchResult, String> {
277        let mut result = FetchResult::default();
278        for lookup in lookups {
279            match lookup {
280                Lookup::Pr(target) => {
281                    let repo = target.repo().clone();
282                    let mr = match self.number(&target)? {
283                        Some(n) => self.mr(&repo, n)?,
284                        None => None,
285                    };
286                    match mr {
287                        Some(mr) => result.prs.push(self.status(&repo, &mr)?),
288                        None => result.not_found.push(target.to_string()),
289                    }
290                }
291                Lookup::Mine(repo) => {
292                    let path = format!(
293                        "{}/merge_requests?scope=created_by_me&state=opened&per_page=100",
294                        project(&repo)
295                    );
296                    for listed in self.rest.list(&path)?.unwrap_or_default() {
297                        let Some(n) = listed["iid"].as_u64() else {
298                            continue;
299                        };
300                        if let Some(mr) = self.mr(&repo, n)? {
301                            result.prs.push(self.status(&repo, &mr)?);
302                        }
303                    }
304                }
305                Lookup::Search { .. } | Lookup::Threads { .. } | Lookup::Contexts { .. } => {}
306            }
307        }
308        Ok(result)
309    }
310
311    fn threads(
312        &mut self,
313        target: &Target,
314        extra: bool,
315        bots: &[String],
316    ) -> Result<Option<PrThreads>, String> {
317        let repo = target.repo().clone();
318        let Some(n) = self.number(target)? else {
319            return Ok(None);
320        };
321        let Some(mr) = self.mr(&repo, n)? else {
322            return Ok(None);
323        };
324        let base = project(&repo);
325        let head_oid = mr["sha"].as_str().unwrap_or_default().to_string();
326        let diff_head = mr["diff_refs"]["head_sha"].as_str().unwrap_or(&head_oid);
327        let head_repo = if mr["source_project_id"] != mr["target_project_id"] {
328            let path = format!("/projects/{}", mr["source_project_id"]);
329            self.rest
330                .json(&path)
331                .ok()
332                .flatten()
333                .and_then(|p| p["path_with_namespace"].as_str().map(str::to_string))
334                .and_then(|p| Repo::on(self.rest.host(), &p))
335        } else {
336            None
337        };
338        // Reading a public MR needs no token, and then there is no viewer.
339        let viewer = self
340            .rest
341            .json("/user")
342            .ok()
343            .flatten()
344            .and_then(|u| u["username"].as_str().map(str::to_string))
345            .unwrap_or_default();
346        let web = mr["web_url"].as_str().unwrap_or_default().to_string();
347        let mut pr = PrThreads {
348            repo: repo.clone(),
349            number: n,
350            node_id: String::new(),
351            head_ref: mr["source_branch"].as_str().unwrap_or_default().to_string(),
352            base_oid: mr["diff_refs"]["base_sha"]
353                .as_str()
354                .unwrap_or_default()
355                .to_string(),
356            head_oid: head_oid.clone(),
357            head_repo,
358            viewer,
359            threads: Vec::new(),
360            others: Vec::new(),
361            unreadable: 0,
362        };
363        let discussions = self
364            .rest
365            .list(&format!(
366                "{base}/merge_requests/{n}/discussions?per_page=100"
367            ))?
368            .unwrap_or_default();
369        for d in discussions {
370            let notes: Vec<&Value> = d["notes"]
371                .as_array()
372                .into_iter()
373                .flatten()
374                .filter(|n| n["system"].as_bool() != Some(true))
375                .collect();
376            let Some(first) = notes.first() else {
377                continue;
378            };
379            let comments: Vec<Comment> = notes.iter().map(|n| note(n, &web)).collect();
380            let author = comments[0].author.clone();
381            let resolvable = first["resolvable"].as_bool() == Some(true);
382            if !resolvable {
383                if extra && d["individual_note"].as_bool() == Some(true) {
384                    pr.others.push(thread(Kind::Comment, &d, comments, bots));
385                }
386                continue;
387            }
388            let mut t = thread(Kind::Thread, &d, comments, bots);
389            t.resolved = !unresolved(&d);
390            let position = &first["position"];
391            if position.is_object() {
392                let (side, line, path) = match position["new_line"].as_u64() {
393                    Some(line) => (Side::Right, Some(line), position["new_path"].as_str()),
394                    None => (
395                        Side::Left,
396                        position["old_line"].as_u64(),
397                        position["old_path"].as_str(),
398                    ),
399                };
400                let line = line.and_then(|l| u32::try_from(l).ok());
401                let range = &position["line_range"]["start"];
402                let start = match side {
403                    Side::Right => range["new_line"].as_u64(),
404                    Side::Left => range["old_line"].as_u64(),
405                }
406                .and_then(|l| u32::try_from(l).ok())
407                .filter(|s| Some(*s) != line);
408                t.outdated = position["head_sha"]
409                    .as_str()
410                    .is_some_and(|h| h != diff_head);
411                t.path = path.map(str::to_string);
412                t.side = side;
413                t.original_line = line;
414                t.line = line.filter(|_| !t.outdated);
415                t.start_line = start.filter(|_| !t.outdated);
416            }
417            t.is_bot = threads::is_bot(&author, bots);
418            pr.threads.push(t);
419        }
420        pr.others
421            .sort_by_key(|t| t.comments.first().map_or(0, |c| c.created));
422        Ok(Some(pr))
423    }
424
425    fn pushed_at(&mut self, pr: &PrThreads, sha: &str) -> Result<Pushed, threads::Lookup> {
426        let sha = threads::sha_prefix(sha)?;
427        let commits = self.commits(pr).map_err(threads::Lookup::Remote)?;
428        // Each version of an MR is one push of its branch.
429        let versions = self
430            .rest
431            .list(&format!(
432                "{}/merge_requests/{}/versions?per_page=100",
433                project(&pr.repo),
434                pr.number
435            ))
436            .map_err(|e| threads::Lookup::Remote(e.message()))?
437            .unwrap_or_default();
438        let activity: Vec<Activity> = versions
439            .iter()
440            .filter_map(|v| {
441                Some(Activity {
442                    after: v["head_commit_sha"].as_str()?.to_string(),
443                    timestamp: utc(&v["created_at"])?,
444                })
445            })
446            .collect();
447        threads::pushed_from(&commits, &activity, &sha)
448    }
449
450    fn files(
451        &mut self,
452        pr: &PrThreads,
453        oid: &str,
454        paths: &[String],
455    ) -> Result<Vec<(String, String)>, String> {
456        let mut out = Vec::new();
457        for path in paths {
458            let url = format!(
459                "{}/repository/files/{}/raw?ref={oid}",
460                project(&pr.repo),
461                encode(path)
462            );
463            let resp = self.rest.get(&url, None)?;
464            if resp.status == 200 {
465                out.push((path.clone(), resp.body));
466            }
467        }
468        Ok(out)
469    }
470
471    /// GitLab's diff is taken against the `base_sha` of the MR's diff refs,
472    /// which is the merge base.
473    fn merge_base(&mut self, pr: &PrThreads) -> Result<String, String> {
474        if pr.base_oid.is_empty() {
475            return Err("GitLab sent the MR without its diff's base".into());
476        }
477        Ok(pr.base_oid.clone())
478    }
479
480    fn on_branch(&mut self, pr: &PrThreads, head: &str) -> Result<bool, String> {
481        Ok(self.commits(pr)?.iter().any(|(oid, _)| oid == head))
482    }
483
484    fn reply(&mut self, pr: &PrThreads, thread: &Thread, body: &str) -> Result<String, String> {
485        let path = format!(
486            "{}/merge_requests/{}/discussions/{}/notes",
487            project(&pr.repo),
488            pr.number,
489            thread.node_id
490        );
491        let resp = self
492            .rest
493            .write(Method::Post, &path, &json!({ "body": body }))?;
494        let note = self
495            .rest
496            .read(&path, resp)?
497            .ok_or("GitLab did not post the reply")?;
498        let id = note["id"].as_u64().ok_or("GitLab did not post the reply")?;
499        let web = thread.url.split('#').next().unwrap_or_default();
500        Ok(format!("{web}#note_{id}"))
501    }
502
503    fn set_resolved(
504        &mut self,
505        pr: &PrThreads,
506        thread: &Thread,
507        resolved: bool,
508    ) -> Result<(), String> {
509        let path = format!(
510            "{}/merge_requests/{}/discussions/{}?resolved={resolved}",
511            project(&pr.repo),
512            pr.number,
513            thread.node_id
514        );
515        let resp = self.rest.write(Method::Put, &path, &json!({}))?;
516        let discussion = self
517            .rest
518            .read(&path, resp)?
519            .ok_or("GitLab no longer has the discussion")?;
520        if unresolved(&discussion) == resolved {
521            let verb = if resolved { "resolve" } else { "unresolve" };
522            return Err(format!("GitLab did not {verb} the thread"));
523        }
524        Ok(())
525    }
526}
527
528/// A thread of `kind` from a discussion's notes.
529fn thread(kind: Kind, d: &Value, comments: Vec<Comment>, bots: &[String]) -> Thread {
530    let first = &comments[0];
531    Thread {
532        id: first.id,
533        node_id: d["id"].as_str().unwrap_or_default().to_string(),
534        kind,
535        path: None,
536        line: None,
537        start_line: None,
538        original_line: None,
539        side: Side::Right,
540        outdated: false,
541        resolved: false,
542        is_bot: threads::is_bot(&first.author, bots),
543        author: first.author.clone(),
544        state: None,
545        url: first.url.clone(),
546        comments,
547        context: None,
548    }
549}
550
551fn note(n: &Value, web: &str) -> Comment {
552    let id = n["id"].as_u64().unwrap_or_default();
553    let created_at = utc(&n["created_at"]).unwrap_or_default();
554    Comment {
555        id,
556        author: n["author"]["username"]
557            .as_str()
558            .unwrap_or("ghost")
559            .to_string(),
560        created: time::parse_utc(&created_at).unwrap_or(0),
561        created_at,
562        body: n["body"].as_str().unwrap_or_default().to_string(),
563        body_truncated: false,
564        suggestion: None,
565        url: format!("{web}#note_{id}"),
566    }
567}
568
569#[cfg(test)]
570mod tests {
571    use super::*;
572
573    #[test]
574    fn merge_states_map_to_githubs() {
575        assert_eq!(
576            merge_state("mergeable", Some(false)),
577            (Mergeability::Mergeable, "clean")
578        );
579        assert_eq!(
580            merge_state("conflict", Some(true)),
581            (Mergeability::Conflicting, "dirty")
582        );
583        assert_eq!(
584            merge_state("need_rebase", Some(false)),
585            (Mergeability::Mergeable, "behind")
586        );
587        assert_eq!(
588            merge_state("checking", None),
589            (Mergeability::Unknown, "unknown")
590        );
591        assert_eq!(
592            merge_state("not_approved", Some(false)),
593            (Mergeability::Mergeable, "blocked")
594        );
595    }
596
597    #[test]
598    fn a_job_allowed_to_fail_passes_with_a_warning() {
599        assert_eq!(
600            bucket(&json!({"status": "failed", "allow_failure": true})),
601            Bucket::Skipped
602        );
603        assert_eq!(bucket(&json!({"status": "failed"})), Bucket::Fail);
604        assert_eq!(bucket(&json!({"status": "running"})), Bucket::Pending);
605        assert_eq!(bucket(&json!({"status": "manual"})), Bucket::Skipped);
606    }
607
608    #[test]
609    fn group_paths_are_one_encoded_project_id() {
610        let repo = Repo::parse("gitlab.com/group/sub/project").unwrap();
611        assert_eq!(project(&repo), "/projects/group%2Fsub%2Fproject");
612    }
613}