Skip to main content

jouet_github/
forgejo.rs

1//! Forgejo and Gitea pull requests behind [`Host`], through the REST API
2//! (v1), which the two share.
3//!
4//! The API has no review threads, only review comments: comments on the
5//! same file and line make one thread, as the web UI shows them, and a
6//! thread's ID is its first comment's. A reply is a new single-comment
7//! review on that line. Checks are the head commit's statuses, which is
8//! where Forgejo Actions reports its jobs.
9//!
10//! Resolving a conversation is only in Gitea's API, from 1.26
11//! (`POST /repos/{owner}/{repo}/pulls/comments/{id}/resolve`); Forgejo's
12//! API has no such endpoint (checked through v16), so it is refused there.
13
14use crate::forge::Forge;
15use crate::host::{Feature, Host};
16use crate::pr::status::{Checks, FetchResult, Fetched, Lookup, Mergeability, PrStatus, State};
17use crate::pr::target::{Repo, Target};
18use crate::pr::threads::{self, Comment, Kind, PrThreads, Pushed, Side, Thread};
19use crate::rest::{MAX_PAGES, Rest, encode, utc};
20use crate::{Failure, Method};
21use jouet_output::time;
22use serde_json::{Value, json};
23use std::collections::BTreeMap;
24
25pub struct Forgejo {
26    rest: Rest,
27    viewer: Option<String>,
28    /// What `/version` said, once asked.
29    version: Option<Option<String>>,
30}
31
32impl Forgejo {
33    pub fn new(host: &str) -> Self {
34        Self {
35            rest: Rest::new(Forge::Forgejo, host),
36            viewer: None,
37            version: None,
38        }
39    }
40
41    /// The REST client, for the CI reads `wait` makes.
42    pub fn rest(&mut self) -> &mut Rest {
43        &mut self.rest
44    }
45
46    /// The PR a target names: a number as is, a branch through its open PR,
47    /// else its most recently updated. `None` when there is none.
48    pub fn number(&mut self, target: &Target) -> Result<Option<u64>, Failure> {
49        let (repo, branch) = match target {
50            Target::Number(_, n) => return Ok(Some(*n)),
51            Target::Branch(repo, branch) => (repo, branch),
52        };
53        for state in ["open", "all"] {
54            let path = format!(
55                "{}/pulls?state={state}&sort=recentupdate&limit=50",
56                base(repo)
57            );
58            let prs = self.rest.list(&path)?.unwrap_or_default();
59            if let Some(n) = prs
60                .iter()
61                .find(|p| p["head"]["ref"].as_str() == Some(branch))
62                .and_then(|p| p["number"].as_u64())
63            {
64                return Ok(Some(n));
65            }
66        }
67        Ok(None)
68    }
69
70    fn viewer(&mut self) -> String {
71        if self.viewer.is_none() {
72            // Reading a public PR needs no token, and then there is no
73            // viewer.
74            let login = self
75                .rest
76                .json("/user")
77                .ok()
78                .flatten()
79                .and_then(|u| u["login"].as_str().map(str::to_string));
80            self.viewer = Some(login.unwrap_or_default());
81        }
82        self.viewer.clone().unwrap_or_default()
83    }
84
85    /// The server's version, such as `1.26.0` (Gitea) or
86    /// `16.0.0+gitea-1.22.0` (Forgejo).
87    fn version(&mut self) -> Option<String> {
88        if self.version.is_none() {
89            let v = self.rest.json("/version").ok().flatten();
90            self.version = Some(v.and_then(|v| v["version"].as_str().map(str::to_string)));
91        }
92        self.version.clone().flatten()
93    }
94
95    fn status(&mut self, repo: &Repo, pr: &Value) -> Result<Fetched, Failure> {
96        let n = pr["number"].as_u64().unwrap_or_default();
97        let state = match (pr["state"].as_str(), pr["merged"].as_bool()) {
98            (_, Some(true)) => State::Merged,
99            (Some("closed"), _) => State::Closed,
100            _ if pr["draft"].as_bool() == Some(true) => State::Draft,
101            _ => State::Open,
102        };
103        let (mergeable, merge_state) = match pr["mergeable"].as_bool() {
104            Some(true) if state == State::Draft => (Mergeability::Mergeable, "draft"),
105            Some(true) => (Mergeability::Mergeable, "clean"),
106            Some(false) => (Mergeability::Conflicting, "dirty"),
107            None => (Mergeability::Unknown, "unknown"),
108        };
109        let head_oid = pr["head"]["sha"].as_str().unwrap_or_default().to_string();
110        let reviews = self
111            .rest
112            .list(&format!("{}/pulls/{n}/reviews?limit=50", base(repo)))?
113            .unwrap_or_default();
114        let comments = review_comments(&mut self.rest, repo, n, &reviews)?;
115        let unresolved = group(comments)
116            .iter()
117            .filter(|t| t[0]["resolver"].is_null())
118            .count();
119        let mut checks = Checks::default();
120        if !head_oid.is_empty() {
121            for s in statuses(&mut self.rest, repo, &head_oid)? {
122                let name = s["context"].as_str().unwrap_or_default().to_string();
123                match s["status"].as_str().unwrap_or_default() {
124                    "success" => checks.pass += 1,
125                    "failure" | "error" => {
126                        checks.fail += 1;
127                        checks.failing.push(name);
128                    }
129                    "warning" | "skipped" => checks.skipped += 1,
130                    _ => checks.pending += 1,
131                }
132            }
133        }
134        let pushed_at = self
135            .rest
136            .list(&format!("{}/pulls/{n}/commits?limit=50", base(repo)))
137            .ok()
138            .flatten()
139            .and_then(|c| utc(&c.last()?["commit"]["committer"]["date"]));
140        Ok(Fetched::new(PrStatus {
141            repo: repo.to_string(),
142            number: n,
143            title: pr["title"].as_str().unwrap_or_default().to_string(),
144            url: pr["html_url"].as_str().unwrap_or_default().to_string(),
145            state,
146            base: pr["base"]["ref"].as_str().unwrap_or_default().to_string(),
147            head: pr["head"]["ref"].as_str().unwrap_or_default().to_string(),
148            head_sha: head_oid.chars().take(10).collect(),
149            head_oid,
150            forge: Some("forgejo"),
151            host: repo.host.clone(),
152            pushed_at,
153            mergeable,
154            merge_state: merge_state.to_string(),
155            checks,
156            review: decision(&reviews),
157            unresolved_threads: u32::try_from(unresolved).unwrap_or(u32::MAX),
158            auto_merge: false,
159            // Entire Gates is a GitHub check run.
160            entire: None,
161            attention: Vec::new(),
162        }))
163    }
164
165    fn commits(&mut self, pr: &PrThreads) -> Result<Vec<(String, i64)>, String> {
166        let list = self
167            .rest
168            .list(&format!(
169                "{}/pulls/{}/commits?limit=50",
170                base(&pr.repo),
171                pr.number
172            ))?
173            .unwrap_or_default();
174        Ok(list
175            .iter()
176            .map(|c| {
177                let oid = c["sha"].as_str().unwrap_or_default().to_string();
178                let at = c["commit"]["committer"]["date"]
179                    .as_str()
180                    .and_then(time::parse_rfc3339)
181                    .unwrap_or(0);
182                (oid, at)
183            })
184            .collect())
185    }
186}
187
188/// A link as Forgejo Actions writes it, by path alone
189/// (`/owner/repo/actions/runs/1/jobs/0`), made absolute on the host's web
190/// server.
191pub fn link(rest: &Rest, url: &str) -> String {
192    if url.starts_with('/') {
193        format!("{}{url}", rest.web_root())
194    } else {
195        url.to_string()
196    }
197}
198
199/// `/repos/OWNER/NAME`.
200pub fn base(repo: &Repo) -> String {
201    format!("/repos/{}/{}", encode(&repo.owner), encode(&repo.name))
202}
203
204/// Every status on `sha`, the latest of each context, through every page.
205pub fn statuses(rest: &mut Rest, repo: &Repo, sha: &str) -> Result<Vec<Value>, Failure> {
206    let mut out: Vec<Value> = Vec::new();
207    for page in 1..=MAX_PAGES {
208        let path = format!("{}/commits/{sha}/status?limit=50&page={page}", base(repo));
209        let Some(combined) = rest.json(&path)? else {
210            break;
211        };
212        let list = combined["statuses"].as_array().cloned().unwrap_or_default();
213        let total = combined["total_count"].as_u64().unwrap_or(0);
214        let empty = list.is_empty();
215        out.extend(list);
216        if empty || out.len() as u64 >= total {
217            break;
218        }
219    }
220    Ok(out)
221}
222
223/// The review decision: changes requested if any reviewer's latest
224/// standing review asks for them, else approved if one approves.
225fn decision(reviews: &[Value]) -> Option<String> {
226    let mut latest: BTreeMap<&str, &str> = BTreeMap::new();
227    for r in reviews {
228        if r["dismissed"].as_bool() == Some(true) {
229            continue;
230        }
231        let (Some(user), Some(state)) = (r["user"]["login"].as_str(), r["state"].as_str()) else {
232            continue;
233        };
234        if matches!(state, "APPROVED" | "REQUEST_CHANGES") {
235            latest.insert(user, state);
236        }
237    }
238    if latest.values().any(|s| *s == "REQUEST_CHANGES") {
239        Some("changes_requested".into())
240    } else if latest.values().any(|s| *s == "APPROVED") {
241        Some("approved".into())
242    } else {
243        None
244    }
245}
246
247/// The line comments of every review that has any.
248fn review_comments(
249    rest: &mut Rest,
250    repo: &Repo,
251    n: u64,
252    reviews: &[Value],
253) -> Result<Vec<Value>, Failure> {
254    let mut out = Vec::new();
255    for r in reviews {
256        let (Some(id), Some(count)) = (r["id"].as_u64(), r["comments_count"].as_u64()) else {
257            continue;
258        };
259        if count == 0 {
260            continue;
261        }
262        let path = format!("{}/pulls/{n}/reviews/{id}/comments", base(repo));
263        out.extend(rest.list(&path)?.unwrap_or_default());
264    }
265    Ok(out)
266}
267
268/// The side and line of a review comment: `position` on the head's side,
269/// `original_position` on the base's.
270fn place(c: &Value) -> (Side, Option<u32>) {
271    let line = |k: &str| {
272        c[k].as_u64()
273            .filter(|l| *l > 0)
274            .and_then(|l| u32::try_from(l).ok())
275    };
276    match line("position") {
277        Some(l) => (Side::Right, Some(l)),
278        None => (Side::Left, line("original_position")),
279    }
280}
281
282/// Review comments grouped into threads by file, side and line, oldest
283/// first in each and threads in the order they started.
284fn group(mut comments: Vec<Value>) -> Vec<Vec<Value>> {
285    comments.sort_by_key(|c| {
286        (
287            c["created_at"]
288                .as_str()
289                .and_then(time::parse_rfc3339)
290                .unwrap_or(0),
291            c["id"].as_u64().unwrap_or(0),
292        )
293    });
294    let mut threads: Vec<Vec<Value>> = Vec::new();
295    for c in comments {
296        let key = |c: &Value| (c["path"].as_str().map(str::to_string), place(c));
297        match threads.iter_mut().find(|t| key(&t[0]) == key(&c)) {
298            Some(t) => t.push(c),
299            None => threads.push(vec![c]),
300        }
301    }
302    threads
303}
304
305fn comment(c: &Value) -> Comment {
306    let created_at = utc(&c["created_at"]).unwrap_or_default();
307    Comment {
308        id: c["id"].as_u64().unwrap_or_default(),
309        author: c["user"]["login"].as_str().unwrap_or("ghost").to_string(),
310        created: time::parse_utc(&created_at).unwrap_or(0),
311        created_at,
312        body: c["body"].as_str().unwrap_or_default().to_string(),
313        body_truncated: false,
314        suggestion: None,
315        url: c["html_url"].as_str().unwrap_or_default().to_string(),
316    }
317}
318
319fn other(kind: Kind, c: Comment, state: Option<String>, bots: &[String]) -> Thread {
320    Thread {
321        id: c.id,
322        node_id: String::new(),
323        kind,
324        path: None,
325        line: None,
326        start_line: None,
327        original_line: None,
328        side: Side::Right,
329        outdated: false,
330        resolved: false,
331        is_bot: threads::is_bot(&c.author, bots),
332        author: c.author.clone(),
333        state,
334        url: c.url.clone(),
335        comments: vec![c],
336        context: None,
337    }
338}
339
340/// The major and minor of a Gitea version, or `None` for Forgejo (whose
341/// version names the Gitea it forked from after a `+`) or one unreadable.
342fn gitea_version(version: &str) -> Option<(u32, u32)> {
343    if version.contains("+gitea") || version.contains("forgejo") {
344        return None;
345    }
346    let mut parts = version.trim_start_matches('v').split(['.', '+', '-']);
347    let major: u32 = parts.next()?.parse().ok()?;
348    let minor: u32 = parts.next()?.parse().ok()?;
349    // Forgejo numbers its releases from 7 up; Gitea is still 1.x.
350    (major == 1).then_some((major, minor))
351}
352
353impl Host for Forgejo {
354    fn forge(&self) -> Forge {
355        Forge::Forgejo
356    }
357
358    fn lacks(&mut self, feature: Feature) -> Option<String> {
359        let host = self.rest.host().to_string();
360        match feature {
361            Feature::Search => Some(
362                "--search takes GitHub's search syntax, which Forgejo has no equivalent of".into(),
363            ),
364            Feature::Runs => Some(format!(
365                "jouet reads Forgejo Actions through the commit statuses it posts, and {host} gives no run of its own; wait on the PR with `jouet wait ci` instead"
366            )),
367            Feature::Explain => Some(
368                "`ci explain` judges a failure by GitHub Actions' run history, which Forgejo's API does not give; use `jouet wait ci` for the failed checks".into(),
369            ),
370            Feature::Resolve => match self.version() {
371                Some(v) => match gitea_version(&v) {
372                    Some((1, minor)) if minor >= 26 => None,
373                    Some(_) => Some(format!(
374                        "{host} runs Gitea {v}, whose API cannot resolve review conversations (Gitea 1.26 added it)"
375                    )),
376                    None => Some(format!(
377                        "{host} runs Forgejo {v}, whose API cannot resolve review conversations (none through Forgejo 16 can)"
378                    )),
379                },
380                // An unknown version is tried; the server says if it cannot.
381                None => None,
382            },
383            Feature::RequiredChecks => Some(
384                "Forgejo's API does not say which checks branch protection requires, so --required would select none; name them with --check"
385                    .into(),
386            ),
387            Feature::Land => Some(
388                "`pr land` merges GitHub PRs only so far; merge the PR with `tea pulls merge` or on the web".into(),
389            ),
390        }
391    }
392
393    fn fetch(&mut self, lookups: Vec<Lookup>) -> Result<FetchResult, String> {
394        let mut result = FetchResult::default();
395        for lookup in lookups {
396            match lookup {
397                Lookup::Pr(target) => {
398                    let repo = target.repo().clone();
399                    let pr = match self.number(&target)? {
400                        Some(n) => self.rest.json(&format!("{}/pulls/{n}", base(&repo)))?,
401                        None => None,
402                    };
403                    match pr {
404                        Some(pr) => result.prs.push(self.status(&repo, &pr)?),
405                        None => result.not_found.push(target.to_string()),
406                    }
407                }
408                Lookup::Mine(repo) => {
409                    let viewer = self.viewer();
410                    if viewer.is_empty() {
411                        return Err(format!(
412                            "--mine needs to know who you are, and {} answered no user for the token; set FORGEJO_TOKEN",
413                            self.rest.host()
414                        ));
415                    }
416                    let path = format!(
417                        "{}/pulls?state=open&poster={}&limit=50",
418                        base(&repo),
419                        encode(&viewer)
420                    );
421                    for pr in self.rest.list(&path)?.unwrap_or_default() {
422                        result.prs.push(self.status(&repo, &pr)?);
423                    }
424                }
425                Lookup::Search { .. } | Lookup::Threads { .. } | Lookup::Contexts { .. } => {}
426            }
427        }
428        Ok(result)
429    }
430
431    fn threads(
432        &mut self,
433        target: &Target,
434        extra: bool,
435        bots: &[String],
436    ) -> Result<Option<PrThreads>, String> {
437        let repo = target.repo().clone();
438        let Some(n) = self.number(target)? else {
439            return Ok(None);
440        };
441        let Some(raw) = self.rest.json(&format!("{}/pulls/{n}", base(&repo)))? else {
442            return Ok(None);
443        };
444        let head_repo = raw["head"]["repo"]["full_name"]
445            .as_str()
446            .filter(|f| *f != repo.to_string())
447            .and_then(|f| Repo::on(self.rest.host(), f));
448        let viewer = self.viewer();
449        let mut pr = PrThreads {
450            repo: repo.clone(),
451            number: n,
452            node_id: String::new(),
453            head_ref: raw["head"]["ref"].as_str().unwrap_or_default().to_string(),
454            head_oid: raw["head"]["sha"].as_str().unwrap_or_default().to_string(),
455            base_oid: raw["merge_base"].as_str().unwrap_or_default().to_string(),
456            head_repo,
457            viewer,
458            threads: Vec::new(),
459            others: Vec::new(),
460            unreadable: 0,
461        };
462        let reviews = self
463            .rest
464            .list(&format!("{}/pulls/{n}/reviews?limit=50", base(&repo)))?
465            .unwrap_or_default();
466        for comments in group(review_comments(&mut self.rest, &repo, n, &reviews)?) {
467            let first = &comments[0];
468            let (side, line) = place(first);
469            let mut t = other(Kind::Thread, comment(first), None, bots);
470            t.path = first["path"].as_str().map(str::to_string);
471            t.side = side;
472            t.line = line;
473            t.original_line = line;
474            t.resolved = !first["resolver"].is_null();
475            t.comments = comments.iter().map(comment).collect();
476            pr.threads.push(t);
477        }
478        if extra {
479            for r in &reviews {
480                let body = r["body"].as_str().unwrap_or_default();
481                if body.trim().is_empty() || r["state"].as_str() == Some("PENDING") {
482                    continue;
483                }
484                let state = match r["state"].as_str().unwrap_or_default() {
485                    "REQUEST_CHANGES" => "changes_requested".to_string(),
486                    "COMMENT" => "commented".to_string(),
487                    s => s.to_ascii_lowercase(),
488                };
489                let mut c = comment(r);
490                c.created_at = utc(&r["submitted_at"]).unwrap_or_default();
491                c.created = time::parse_utc(&c.created_at).unwrap_or(0);
492                pr.others.push(other(Kind::Review, c, Some(state), bots));
493            }
494            let path = format!("{}/issues/{n}/comments?limit=50", base(&repo));
495            for c in self.rest.list(&path)?.unwrap_or_default() {
496                if c["body"].as_str().is_some_and(|b| !b.trim().is_empty()) {
497                    pr.others
498                        .push(other(Kind::Comment, comment(&c), None, bots));
499                }
500            }
501            pr.others
502                .sort_by_key(|t| t.comments.first().map_or(0, |c| c.created));
503        }
504        Ok(Some(pr))
505    }
506
507    /// Forgejo keeps no push log, so a commit's push time is its commit
508    /// time, which can only be earlier.
509    fn pushed_at(&mut self, pr: &PrThreads, sha: &str) -> Result<Pushed, threads::Lookup> {
510        let sha = threads::sha_prefix(sha)?;
511        let commits = self.commits(pr).map_err(threads::Lookup::Remote)?;
512        threads::pushed_from(&commits, &[], &sha)
513    }
514
515    fn files(
516        &mut self,
517        pr: &PrThreads,
518        oid: &str,
519        paths: &[String],
520    ) -> Result<Vec<(String, String)>, String> {
521        let mut out = Vec::new();
522        for path in paths {
523            let segments: Vec<String> = path.split('/').map(encode).collect();
524            let url = format!("{}/raw/{}?ref={oid}", base(&pr.repo), segments.join("/"));
525            let resp = self.rest.get(&url, None)?;
526            if resp.status == 200 {
527                out.push((path.clone(), resp.body));
528            }
529        }
530        Ok(out)
531    }
532
533    fn merge_base(&mut self, pr: &PrThreads) -> Result<String, String> {
534        if pr.base_oid.is_empty() {
535            return Err("Forgejo sent the PR without its merge base".into());
536        }
537        Ok(pr.base_oid.clone())
538    }
539
540    fn on_branch(&mut self, pr: &PrThreads, head: &str) -> Result<bool, String> {
541        Ok(self.commits(pr)?.iter().any(|(oid, _)| oid == head))
542    }
543
544    fn reply(&mut self, pr: &PrThreads, thread: &Thread, body: &str) -> Result<String, String> {
545        let path = thread.path.as_deref().ok_or("the thread is on no file")?;
546        let line = thread
547            .original_line
548            .ok_or("the thread is on no line of the file")?;
549        let mut comment = json!({ "path": path, "body": body });
550        let key = match thread.side {
551            Side::Right => "new_position",
552            Side::Left => "old_position",
553        };
554        comment[key] = line.into();
555        let url = format!("{}/pulls/{}/reviews", base(&pr.repo), pr.number);
556        let request = json!({
557            "event": "COMMENT",
558            "body": "",
559            "commit_id": pr.head_oid,
560            "comments": [comment],
561        });
562        let resp = self.rest.write(Method::Post, &url, &request)?;
563        let review = self
564            .rest
565            .read(&url, resp)?
566            .ok_or("Forgejo did not post the reply")?;
567        Ok(review["html_url"]
568            .as_str()
569            .filter(|u| !u.is_empty())
570            .map_or_else(|| thread.url.clone(), str::to_string))
571    }
572
573    fn set_resolved(
574        &mut self,
575        pr: &PrThreads,
576        thread: &Thread,
577        resolved: bool,
578    ) -> Result<(), String> {
579        let verb = if resolved { "resolve" } else { "unresolve" };
580        let path = format!("{}/pulls/comments/{}/{verb}", base(&pr.repo), thread.id);
581        let resp = self.rest.write(Method::Post, &path, &json!({}))?;
582        match resp.status {
583            200..=299 => Ok(()),
584            404 | 405 => Err(format!(
585                "{} has no API to {verb} review conversations (Gitea 1.26 added it; Forgejo has none)",
586                self.rest.host()
587            )),
588            status => Err(self.rest.refused(status, &resp.body).message()),
589        }
590    }
591}
592
593#[cfg(test)]
594mod tests {
595    use super::*;
596
597    #[test]
598    fn forgejo_versions_are_told_from_gitea_ones() {
599        assert_eq!(gitea_version("1.26.0"), Some((1, 26)));
600        assert_eq!(gitea_version("1.25.3"), Some((1, 25)));
601        assert_eq!(gitea_version("16.0.0-dev-798-568c49e1+gitea-1.22.0"), None);
602        assert_eq!(gitea_version("11.0.1+gitea-1.22.0"), None);
603    }
604
605    #[test]
606    fn comments_on_one_line_are_one_thread() {
607        let c = |id: u64, line: u64, at: &str| json!({ "id": id, "path": "a.rs", "position": line, "created_at": at });
608        let threads = group(vec![
609            c(3, 5, "2026-01-01T00:02:00Z"),
610            c(1, 5, "2026-01-01T00:00:00Z"),
611            c(2, 9, "2026-01-01T00:01:00Z"),
612        ]);
613        let ids: Vec<Vec<u64>> = threads
614            .iter()
615            .map(|t| t.iter().map(|c| c["id"].as_u64().unwrap()).collect())
616            .collect();
617        assert_eq!(ids, [vec![1, 3], vec![2]]);
618    }
619
620    #[test]
621    fn a_standing_request_for_changes_wins() {
622        let r = |user: &str, state: &str| json!({ "user": { "login": user }, "state": state });
623        assert_eq!(
624            decision(&[r("a", "APPROVED"), r("b", "REQUEST_CHANGES")]).as_deref(),
625            Some("changes_requested")
626        );
627        assert_eq!(
628            decision(&[r("a", "REQUEST_CHANGES"), r("a", "APPROVED")]).as_deref(),
629            Some("approved")
630        );
631        assert_eq!(decision(&[r("a", "COMMENT")]), None);
632    }
633}