vcs_gitlab/

lib.rs

#![cfg_attr(docsrs, feature(doc_cfg))]
#![deny(rustdoc::broken_intra_doc_links)]
//! `vcs-gitlab` — automate GitLab from Rust by driving the `glab` CLI.
//!
//! It shells out to the installed `glab` binary, asks for `--output json`, and
//! deserializes the result into typed values — so you get *glab's own* behaviour,
//! host config, and credential handling, not a reimplementation of the GitLab API
//! client. Async throughout, structured errors, and mockable. Every command runs
//! inside an OS **job** (via [`processkit`]) so a `glab` subprocess tree can never
//! be orphaned, and honours an optional per-client
//! [timeout](GitLab::default_timeout).
//!
//! # The surface
//!
//! The modelled surface is the **lean merge-request lifecycle** — auth, project
//! view, the MR lifecycle, plus issues and releases. It deserializes `glab …
//! --output json` (GitLab's REST JSON, which `glab` passes through) into typed
//! structs; it never scrapes human-readable output. The sibling
//! [`vcs-github`](https://crates.io/crates/vcs-github) and
//! [`vcs-gitea`](https://crates.io/crates/vcs-gitea) wrappers mirror this shape,
//! and the [`vcs-forge`](https://crates.io/crates/vcs-forge) facade unifies all
//! three.
//!
//! - **[`GitLabApi`]** — the object-safe trait every operation lives on. Depend on
//!   `&dyn GitLabApi` (or generically on `impl GitLabApi`) so a test can swap the
//!   real client for a double. Project-scoped methods take the working directory
//!   as the first argument and return typed results ([`Project`],
//!   [`MergeRequest`], [`Issue`], [`Release`], [`CiStatus`]) or a structured
//!   [`Error`]. Unmodelled `glab` commands go through [`run`](GitLabApi::run).
//! - **[`GitLab`]** — the real client. [`GitLab::new`] uses the job-backed runner;
//!   [`GitLab::with_runner`] injects a fake one for tests. It is generic over the
//!   [`ProcessRunner`] seam, defaulting to the production runner.
//! - **[`GitLabAt`]** — a cwd-bound view ([`GitLab::at`]) whose project-scoped
//!   methods drop the leading `dir`, so `glab.at(dir).mr_list()` reads as
//!   `glab.mr_list(dir)` — handy when one client drives one checkout.
//! - **Builder specs** for the multi-option commands — [`MrCreate`] (title, body,
//!   optional source/target branch) and the [`MergeStrategy`] enum
//!   (`Merge`/`Squash`/`Rebase`) — `#[non_exhaustive]`, built with a constructor +
//!   chained setters, named after the flags they emit.
//! - **[`auth_status`](GitLabApi::auth_status)** — a best-effort signal, *not* a
//!   guarantee: a long-standing glab bug can make `glab auth status` exit `0` even
//!   when unauthenticated, so a `true` means "probably"; a subsequent API call is
//!   the real test. A `false`, spawn failure, or timeout are faithful.
//!
//! # Recipes
//!
//! Read state — depend on the trait so the same code takes a real client or a mock:
//!
//! ```no_run
//! use std::path::Path;
//! use vcs_gitlab::{GitLab, GitLabApi};
//! # async fn demo() -> Result<(), processkit::Error> {
//! let glab = GitLab::new();
//! let dir = Path::new(".");
//! for mr in glab.mr_list(dir).await? {                 // up to 100 open MRs
//!     println!("!{} [{}] {}", mr.iid, mr.state, mr.title);
//! }
//! # Ok(()) }
//! ```
//!
//! Mutate through the builder specs — `mr_merge` merges *immediately*
//! (`--auto-merge=false`) rather than enabling merge-when-pipeline-succeeds:
//!
//! ```no_run
//! use std::path::Path;
//! use vcs_gitlab::{GitLab, GitLabApi, MergeStrategy, MrCreate};
//! # async fn demo(glab: &GitLab) -> Result<(), processkit::Error> {
//! let dir = Path::new(".");
//! let url = glab
//!     .mr_create(dir, MrCreate::new("Add streaming", "Implements …").target("main"))
//!     .await?;                                          // the new MR's URL
//! glab.mr_merge(dir, 12, MergeStrategy::Squash).await?;
//! # let _ = url; Ok(()) }
//! ```
//!
//! # Testing
//!
//! Two seams: enable the **`mock`** feature for a `mockall`-generated
//! `MockGitLabApi` (stub whole methods), or inject a
//! [`ScriptedRunner`](processkit::ScriptedRunner) with [`GitLab::with_runner`] to
//! exercise the *real* argv-building and JSON parsing against canned output. The
//! cross-cutting testing patterns live in
//! [vcs-testkit's guide](https://docs.rs/vcs-testkit/latest/vcs_testkit/guide/testing/).
//!
//! # In-depth guide
//!
//! Beyond this page, this crate ships a full how-to guide — rendered on docs.rs
//! from `docs/`. See the [`guide`] module.

use std::path::Path;

use processkit::ProcessRunner;
// Re-export the processkit types in this crate's public API (also brings
// `Error`/`Result`/`ProcessResult` into scope here).
pub use processkit::{Error, ProcessResult, Result};
// Re-exported under the `cancellation` feature so a consumer can name the token
// for `default_cancel_on` without taking a direct `processkit` dependency.
#[cfg(feature = "cancellation")]
#[cfg_attr(docsrs, doc(cfg(feature = "cancellation")))]
pub use processkit::CancellationToken;

mod parse;
pub use parse::{CiStatus, Issue, MergeRequest, Project, Release};

/// Options for [`GitLabApi::mr_create`] (`glab mr create`).
///
/// `#[non_exhaustive]`, so build it through [`MrCreate::new`] and the chained
/// setters rather than a struct literal.
#[derive(Debug, Clone)]
#[non_exhaustive]
pub struct MrCreate {
    /// The MR title (`--title`).
    pub title: String,
    /// The MR description (`--description`).
    pub body: String,
    /// The source branch (`--source-branch`); `None` = the current branch.
    pub source: Option<String>,
    /// The target branch (`--target-branch`); `None` = the project default.
    pub target: Option<String>,
}

impl MrCreate {
    /// An MR with `title` and `body`, source/target left to glab's defaults
    /// (current branch → project default).
    pub fn new(title: impl Into<String>, body: impl Into<String>) -> Self {
        Self {
            title: title.into(),
            body: body.into(),
            source: None,
            target: None,
        }
    }

    /// Set the source branch (`--source-branch`) instead of the current branch.
    pub fn source(mut self, source: impl Into<String>) -> Self {
        self.source = Some(source.into());
        self
    }

    /// Set the target branch (`--target-branch`) instead of the project default.
    pub fn target(mut self, target: impl Into<String>) -> Self {
        self.target = Some(target.into());
        self
    }
}

/// Name of the underlying CLI binary this crate drives.
///
/// Note on injection safety: most of the surface has **no bare positional string
/// slot** for a caller value — MR/issue ids are `u64` (never flag-like), the
/// title/body/branch arguments ride in flag-VALUE positions (`--title <t>`,
/// `--source-branch <b>`) where glab consumes the next token verbatim, and
/// `run`/`run_args` are the caller-owns-the-argv escape hatch. The one exception
/// is [`release_view`](GitLabApi::release_view)'s bare `<tag>` positional, which
/// is guarded with `reject_flag_like` (mirroring `vcs-github`'s
/// `api`/`release_view`); guard any future bare positional the same way.
pub const BINARY: &str = "glab";

/// Injection guard for bare positional argv slots: a caller-supplied value with
/// a leading `-` would be parsed by glab's CLI as a *flag*, and an empty value
/// changes a command's meaning. Refuse both before anything spawns. Flag-VALUE
/// positions (`--title <t>`, `--source-branch <b>`) need no guard — glab consumes
/// the next token verbatim there.
fn reject_flag_like(what: &str, value: &str) -> Result<()> {
    vcs_cli_support::reject_flag_like(BINARY, what, value)
}

/// How [`GitLabApi::mr_merge`] merges the MR. GitLab's default is a merge commit;
/// `Squash`/`Rebase` add the corresponding flag.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[non_exhaustive]
pub enum MergeStrategy {
    /// A merge commit (glab's default — no extra flag).
    Merge,
    /// Squash the commits into one (`--squash`).
    Squash,
    /// Rebase the source onto the target (`--rebase`).
    Rebase,
}

impl MergeStrategy {
    /// The glab flag for this strategy, or `None` for the default merge commit.
    fn flag(self) -> Option<&'static str> {
        match self {
            MergeStrategy::Merge => None,
            MergeStrategy::Squash => Some("--squash"),
            MergeStrategy::Rebase => Some("--rebase"),
        }
    }
}

/// The GitLab operations this crate exposes — the interface consumers code
/// against and mock in tests. The **lean MR lifecycle**; reach unmodelled `glab`
/// commands through [`run`](GitLabApi::run).
#[cfg_attr(feature = "mock", mockall::automock)]
#[async_trait::async_trait]
pub trait GitLabApi: Send + Sync {
    /// Run `glab <args>`, returning trimmed stdout (throws on a non-zero exit).
    async fn run(&self, args: &[String]) -> Result<String>;
    /// Like [`GitLabApi::run`] but never errors on a non-zero exit — returns the
    /// captured [`ProcessResult`].
    async fn run_raw(&self, args: &[String]) -> Result<ProcessResult<String>>;
    /// Installed GitLab CLI version (`glab --version`).
    async fn version(&self) -> Result<String>;
    /// Whether the user is authenticated (`glab auth status` exits zero). Reflects
    /// the exit code as a bool — any non-zero exit reads as `false`, never an
    /// error; only a spawn failure or timeout errors.
    ///
    /// **Caveat:** this reflects glab's exit code, and a long-standing glab bug
    /// ([gitlab-org/cli#911]) can make `glab auth status` exit `0` even when *not*
    /// authenticated, so a `true` here is a best-effort signal, not a guarantee —
    /// a subsequent API call is the real test. A `false`, a spawn failure, or a
    /// timeout are still reported faithfully.
    ///
    /// [gitlab-org/cli#911]: https://gitlab.com/gitlab-org/cli/-/issues/911
    async fn auth_status(&self) -> Result<bool>;
    /// The project for `dir` (`glab repo view --output json`).
    async fn repo_view(&self, dir: &Path) -> Result<Project>;
    /// Open merge requests for `dir`
    /// (`glab mr list --per-page 100 --output json`). Returns up to 100 (100 is
    /// the GitLab API per-page max); use [`run`](GitLabApi::run) for more.
    async fn mr_list(&self, dir: &Path) -> Result<Vec<MergeRequest>>;
    /// A single merge request by its project-scoped id
    /// (`glab mr view <id> --output json`).
    async fn mr_view(&self, dir: &Path, id: u64) -> Result<MergeRequest>;
    /// Open a merge request, returning the command's output (the MR URL on
    /// success) (`glab mr create`). The [`MrCreate`] spec carries the title,
    /// body, and the optional source (`None` = the current branch) and target
    /// (`None` = the project default) branches.
    async fn mr_create(&self, dir: &Path, spec: MrCreate) -> Result<String>;
    /// Merge a merge request **immediately** (`glab mr merge <id> --yes
    /// --auto-merge=false [--squash|--rebase]`) — `--auto-merge=false` overrides
    /// glab's default of enabling merge-when-pipeline-succeeds. See
    /// [`MergeStrategy`].
    async fn mr_merge(&self, dir: &Path, id: u64, strategy: MergeStrategy) -> Result<()>;
    /// Mark a draft merge request as ready (`glab mr update <id> --ready`).
    async fn mr_ready(&self, dir: &Path, id: u64) -> Result<()>;
    /// Close a merge request without merging (`glab mr close <id>`).
    async fn mr_close(&self, dir: &Path, id: u64) -> Result<()>;
    /// The MR's pipeline status, bucketed (`glab mr view <id> --output json`,
    /// reading `head_pipeline.status`). [`CiStatus::None`] when no pipeline ran.
    async fn mr_checks(&self, dir: &Path, id: u64) -> Result<CiStatus>;
    /// Open issues for `dir`
    /// (`glab issue list --per-page 100 --output json`). Returns up to 100 (100
    /// is the GitLab API per-page max); use [`run`](GitLabApi::run) for more.
    async fn issue_list(&self, dir: &Path) -> Result<Vec<Issue>>;
    /// A single issue by its project-scoped id (`iid`)
    /// (`glab issue view <number> --output json`).
    async fn issue_view(&self, dir: &Path, number: u64) -> Result<Issue>;
    /// Open an issue, returning the command's output (the issue URL on success)
    /// (`glab issue create --title <t> --description <d> --yes`). `--yes` skips
    /// glab's interactive submission prompt — mirrors
    /// [`mr_create`](GitLabApi::mr_create).
    async fn issue_create(&self, dir: &Path, title: &str, body: &str) -> Result<String>;
    /// Releases for `dir` (`glab release list --per-page 100 --output json`).
    /// Returns up to 100 (100 is the GitLab API per-page max); use
    /// [`run`](GitLabApi::run) for more.
    async fn release_list(&self, dir: &Path) -> Result<Vec<Release>>;
    /// A single release by its tag (`glab release view <tag> --output json`).
    /// The `tag` is a bare positional, so it is guarded with
    /// `reject_flag_like` (a leading `-` or empty value is rejected before any
    /// process spawns).
    async fn release_view(&self, dir: &Path, tag: &str) -> Result<Release>;
}

processkit::cli_client!(
    /// The real GitLab client. Generic over the [`ProcessRunner`] so tests can
    /// inject a fake process executor; `GitLab::new()` uses the real job-backed
    /// runner.
    pub struct GitLab => BINARY
);

#[async_trait::async_trait]
impl<R: ProcessRunner> GitLabApi for GitLab<R> {
    async fn run(&self, args: &[String]) -> Result<String> {
        self.core.run(self.core.command(args)).await
    }

    async fn run_raw(&self, args: &[String]) -> Result<ProcessResult<String>> {
        self.core.output(self.core.command(args)).await
    }

    async fn version(&self) -> Result<String> {
        self.core.run(self.core.command(["--version"])).await
    }

    async fn auth_status(&self) -> Result<bool> {
        // `glab auth status` exits 0 when authenticated, non-zero when not — an
        // exit-code answer. `exit_code` reads the exit code without erroring on a
        // non-zero one (a spawn failure or timeout still errors), so ANY non-zero
        // exit — not just the documented 1 — maps to "not authenticated" rather
        // than surfacing as an error (glab's exit codes are not contractual; see
        // the #911 caveat on the trait method). `probe` would reject an unusual
        // exit code.
        Ok(self
            .core
            .exit_code(self.core.command(["auth", "status"]))
            .await?
            == 0)
    }

    async fn repo_view(&self, dir: &Path) -> Result<Project> {
        self.core
            .try_parse(
                self.core
                    .command_in(dir, ["repo", "view", "--output", "json"]),
                parse::from_json,
            )
            .await
    }

    async fn mr_list(&self, dir: &Path) -> Result<Vec<MergeRequest>> {
        // `--per-page 100` (the GitLab API max) overrides glab's default page size
        // of 30, which would otherwise silently truncate the list.
        self.core
            .try_parse(
                self.core
                    .command_in(dir, ["mr", "list", "--per-page", "100", "--output", "json"]),
                parse::from_json,
            )
            .await
    }

    async fn mr_view(&self, dir: &Path, id: u64) -> Result<MergeRequest> {
        let id = id.to_string();
        self.core
            .try_parse(
                self.core
                    .command_in(dir, ["mr", "view", id.as_str(), "--output", "json"]),
                parse::from_json,
            )
            .await
    }

    async fn mr_create(&self, dir: &Path, spec: MrCreate) -> Result<String> {
        // `--yes` skips glab's interactive submission confirmation (a headless run
        // would otherwise hang waiting on the prompt).
        let mut args = vec![
            "mr",
            "create",
            "--title",
            spec.title.as_str(),
            "--description",
            spec.body.as_str(),
            "--yes",
        ];
        if let Some(source) = spec.source.as_deref() {
            args.push("--source-branch");
            args.push(source);
        }
        if let Some(target) = spec.target.as_deref() {
            args.push("--target-branch");
            args.push(target);
        }
        self.core.run(self.core.command_in(dir, args)).await
    }

    async fn mr_merge(&self, dir: &Path, id: u64, strategy: MergeStrategy) -> Result<()> {
        let id = id.to_string();
        // `--yes` skips the confirmation prompt. `--auto-merge=false` forces an
        // *immediate* merge: glab's `--auto-merge` defaults to `true`, which —
        // with a running pipeline — would enable merge-when-pipeline-succeeds
        // instead of merging now, so a method named `mr_merge` wouldn't actually
        // merge. The strategy flag is added only for squash/rebase (a plain merge
        // commit is glab's default).
        let mut args = vec!["mr", "merge", id.as_str(), "--yes", "--auto-merge=false"];
        if let Some(flag) = strategy.flag() {
            args.push(flag);
        }
        self.core.run_unit(self.core.command_in(dir, args)).await
    }

    async fn mr_ready(&self, dir: &Path, id: u64) -> Result<()> {
        let id = id.to_string();
        self.core
            .run_unit(
                self.core
                    .command_in(dir, ["mr", "update", id.as_str(), "--ready"]),
            )
            .await
    }

    async fn mr_close(&self, dir: &Path, id: u64) -> Result<()> {
        let id = id.to_string();
        self.core
            .run_unit(self.core.command_in(dir, ["mr", "close", id.as_str()]))
            .await
    }

    async fn mr_checks(&self, dir: &Path, id: u64) -> Result<CiStatus> {
        let id = id.to_string();
        self.core
            .try_parse(
                self.core
                    .command_in(dir, ["mr", "view", id.as_str(), "--output", "json"]),
                parse::parse_ci_status,
            )
            .await
    }

    async fn issue_list(&self, dir: &Path) -> Result<Vec<Issue>> {
        // `--per-page 100` (the GitLab API max) overrides glab's default page
        // size of 30, which would otherwise silently truncate the list.
        self.core
            .try_parse(
                self.core.command_in(
                    dir,
                    ["issue", "list", "--per-page", "100", "--output", "json"],
                ),
                parse::from_json,
            )
            .await
    }

    async fn issue_view(&self, dir: &Path, number: u64) -> Result<Issue> {
        let number = number.to_string();
        self.core
            .try_parse(
                self.core
                    .command_in(dir, ["issue", "view", number.as_str(), "--output", "json"]),
                parse::from_json,
            )
            .await
    }

    async fn issue_create(&self, dir: &Path, title: &str, body: &str) -> Result<String> {
        // `--yes` skips glab's interactive submission confirmation (a headless
        // run would otherwise hang on the prompt) — same as `mr_create`.
        self.core
            .run(self.core.command_in(
                dir,
                [
                    "issue",
                    "create",
                    "--title",
                    title,
                    "--description",
                    body,
                    "--yes",
                ],
            ))
            .await
    }

    async fn release_list(&self, dir: &Path) -> Result<Vec<Release>> {
        // `--per-page 100` (the GitLab API max) overrides glab's default page
        // size of 30, which would otherwise silently truncate the list.
        self.core
            .try_parse(
                self.core.command_in(
                    dir,
                    ["release", "list", "--per-page", "100", "--output", "json"],
                ),
                parse::from_json,
            )
            .await
    }

    async fn release_view(&self, dir: &Path, tag: &str) -> Result<Release> {
        reject_flag_like("tag", tag)?;
        self.core
            .try_parse(
                self.core
                    .command_in(dir, ["release", "view", tag, "--output", "json"]),
                parse::from_json,
            )
            .await
    }
}

impl<R: ProcessRunner> GitLab<R> {
    /// Run `glab <args>` over string slices — `glab.run_args(&["mr", "list"])`
    /// without allocating a `Vec<String>`. Inherent (not on the object-safe
    /// trait), so it can take `&[&str]`; forwards to the same path as
    /// [`GitLabApi::run`].
    pub async fn run_args(&self, args: &[&str]) -> Result<String> {
        self.core.run(self.core.command(args)).await
    }

    /// Like [`run_args`](GitLab::run_args) but never errors on a non-zero exit
    /// (mirrors [`GitLabApi::run_raw`]).
    pub async fn run_raw_args(&self, args: &[&str]) -> Result<ProcessResult<String>> {
        self.core.output(self.core.command(args)).await
    }

    /// Bind a working directory, so the project-scoped methods omit that argument:
    /// `glab.at(dir).mr_list()` runs [`mr_list`](GitLabApi::mr_list) against `dir`.
    pub fn at<'a>(&'a self, dir: &'a Path) -> GitLabAt<'a, R> {
        GitLabAt { glab: self, dir }
    }
}

/// A [`GitLab`] client with a working directory bound, so its project-scoped
/// methods drop the leading `dir` argument (`glab.at(dir).mr_list()`). Construct
/// one with [`GitLab::at`].
pub struct GitLabAt<'a, R: ProcessRunner = processkit::JobRunner> {
    glab: &'a GitLab<R>,
    dir: &'a Path,
}

// Hand-written rather than derived: holding only references, the view is `Copy`
// for *every* runner. `#[derive(Copy)]` would add a spurious `R: Copy` bound the
// default `JobRunner` doesn't satisfy, silently dropping `Copy` on the handle.
impl<R: ProcessRunner> Clone for GitLabAt<'_, R> {
    fn clone(&self) -> Self {
        *self
    }
}
impl<R: ProcessRunner> Copy for GitLabAt<'_, R> {}

/// Generate [`GitLabAt`] forwarders: `bare` methods forward verbatim, `dir`
/// methods inject `self.dir` as the first argument.
macro_rules! gitlab_at_forwarders {
    (
        bare { $( fn $bn:ident( $($ba:ident: $bt:ty),* $(,)? ) -> $br:ty; )* }
        dir  { $( fn $dn:ident( $($da:ident: $dt:ty),* $(,)? ) -> $dr:ty; )* }
    ) => {
        impl<'a, R: ProcessRunner> GitLabAt<'a, R> {
            $(
                #[doc = concat!("Bound form of [`GitLab`]'s `", stringify!($bn), "`.")]
                pub async fn $bn(&self, $($ba: $bt),*) -> $br {
                    self.glab.$bn($($ba),*).await
                }
            )*
            $(
                #[doc = concat!("Bound form of [`GitLab`]'s `", stringify!($dn), "` (with `dir` pre-bound).")]
                pub async fn $dn(&self, $($da: $dt),*) -> $dr {
                    self.glab.$dn(self.dir, $($da),*).await
                }
            )*
        }
    };
}

gitlab_at_forwarders! {
    bare {
        fn run(args: &[String]) -> Result<String>;
        fn run_raw(args: &[String]) -> Result<ProcessResult<String>>;
        fn run_args(args: &[&str]) -> Result<String>;
        fn run_raw_args(args: &[&str]) -> Result<ProcessResult<String>>;
        fn version() -> Result<String>;
        fn auth_status() -> Result<bool>;
    }
    dir {
        fn repo_view() -> Result<Project>;
        fn mr_list() -> Result<Vec<MergeRequest>>;
        fn mr_view(id: u64) -> Result<MergeRequest>;
        fn mr_create(spec: MrCreate) -> Result<String>;
        fn mr_merge(id: u64, strategy: MergeStrategy) -> Result<()>;
        fn mr_ready(id: u64) -> Result<()>;
        fn mr_close(id: u64) -> Result<()>;
        fn mr_checks(id: u64) -> Result<CiStatus>;
        fn issue_list() -> Result<Vec<Issue>>;
        fn issue_view(number: u64) -> Result<Issue>;
        fn issue_create(title: &str, body: &str) -> Result<String>;
        fn release_list() -> Result<Vec<Release>>;
        fn release_view(tag: &str) -> Result<Release>;
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use processkit::{RecordingRunner, Reply, ScriptedRunner};

    #[test]
    fn binary_name_is_glab() {
        assert_eq!(BINARY, "glab");
    }

    // Compile-time guard: the bound view stays `Copy` for the default `JobRunner`.
    #[allow(dead_code)]
    fn bound_view_is_copy_for_default_runner() {
        fn assert_copy<T: Copy>() {}
        assert_copy::<GitLabAt<'static, processkit::JobRunner>>();
    }

    // The bound view (`glab.at(dir)`) must produce byte-identical argv to the
    // dir-taking call.
    #[tokio::test]
    async fn bound_view_matches_dir_taking_calls() {
        let dir = Path::new("/repo");
        let rec = RecordingRunner::replying(Reply::ok("[]"));
        let glab = GitLab::with_runner(&rec);

        glab.mr_list(dir).await.unwrap();
        glab.at(dir).mr_list().await.unwrap();
        glab.mr_ready(dir, 7).await.unwrap();
        glab.at(dir).mr_ready(7).await.unwrap();

        let calls = rec.calls();
        assert_eq!(calls[0].args_str(), calls[1].args_str());
        assert_eq!(calls[2].args_str(), calls[3].args_str());
        assert_eq!(calls[1].cwd.as_deref(), Some(dir.as_os_str()));
    }

    #[tokio::test]
    async fn run_args_forwards_str_slices() {
        let glab =
            GitLab::with_runner(ScriptedRunner::new().on(["api", "/version"], Reply::ok("ok\n")));
        assert_eq!(glab.run_args(&["api", "/version"]).await.unwrap(), "ok");
    }

    // Hermetic: real mr_list() arg-building + JSON deserialization against canned
    // output — no `glab` binary or network needed, so this runs on CI.
    #[tokio::test]
    async fn mr_list_parses_scripted_json() {
        let json = r#"[{"iid":7,"title":"Add X","state":"opened","source_branch":"feat/x","target_branch":"main","web_url":"u","draft":false}]"#;
        let glab = GitLab::with_runner(ScriptedRunner::new().on(["mr", "list"], Reply::ok(json)));
        let mrs = glab.mr_list(Path::new(".")).await.expect("mr_list");
        assert_eq!(mrs.len(), 1);
        assert_eq!(mrs[0].iid, 7);
        assert_eq!(mrs[0].target_branch, "main");
    }

    // mr_list builds the `--per-page 100 --output json` argv — the explicit
    // per-page max overrides glab's default page size (30) so the list is not
    // silently truncated.
    #[tokio::test]
    async fn mr_list_builds_output_json_argv() {
        let rec = RecordingRunner::replying(Reply::ok("[]"));
        let glab = GitLab::with_runner(&rec);
        glab.mr_list(Path::new("/repo")).await.expect("mr_list");
        assert_eq!(
            rec.only_call().args_str(),
            ["mr", "list", "--per-page", "100", "--output", "json"]
        );
    }

    // Hermetic: auth_status reflects the exit code without erroring. ANY non-zero
    // exit — not just the documented 1 — must read as `false`, never an error.
    #[tokio::test]
    async fn auth_status_reads_exit_code() {
        let yes = GitLab::with_runner(ScriptedRunner::new().on(["auth"], Reply::ok("")));
        assert!(yes.auth_status().await.unwrap());
        let no = GitLab::with_runner(
            ScriptedRunner::new().on(["auth"], Reply::fail(1, "not logged in")),
        );
        assert!(!no.auth_status().await.unwrap());
        // An unexpected exit code (e.g. 2) is still just "not authenticated".
        let weird = GitLab::with_runner(ScriptedRunner::new().on(["auth"], Reply::fail(2, "boom")));
        assert!(!weird.auth_status().await.unwrap());
    }

    // A timed-out auth check must error, not silently report "not authenticated".
    #[tokio::test]
    async fn auth_status_errors_on_timeout() {
        let glab = GitLab::with_runner(ScriptedRunner::new().on(["auth"], Reply::timeout()));
        assert!(matches!(
            glab.auth_status().await.unwrap_err(),
            Error::Timeout { .. }
        ));
    }

    // mr_create assembles title/description/--yes, then the optional source/target
    // branch flags, and returns the trimmed output (the MR URL).
    #[tokio::test]
    async fn mr_create_appends_source_and_target() {
        let rec = RecordingRunner::replying(Reply::ok("https://gl/mr/9\n"));
        let glab = GitLab::with_runner(&rec);
        let url = glab
            .mr_create(
                Path::new("/repo"),
                MrCreate::new("T", "B").source("feat/x").target("main"),
            )
            .await
            .expect("mr_create");
        assert_eq!(url, "https://gl/mr/9");
        assert_eq!(
            rec.only_call().args_str(),
            [
                "mr",
                "create",
                "--title",
                "T",
                "--description",
                "B",
                "--yes",
                "--source-branch",
                "feat/x",
                "--target-branch",
                "main"
            ]
        );
    }

    // With no source/target, mr_create omits both branch flags.
    #[tokio::test]
    async fn mr_create_omits_branch_flags_when_none() {
        let rec = RecordingRunner::replying(Reply::ok("https://gl/mr/1\n"));
        let glab = GitLab::with_runner(&rec);
        glab.mr_create(Path::new("/repo"), MrCreate::new("T", "B"))
            .await
            .expect("mr_create");
        assert_eq!(
            rec.only_call().args_str(),
            [
                "mr",
                "create",
                "--title",
                "T",
                "--description",
                "B",
                "--yes"
            ]
        );
    }

    // mr_merge adds `--yes`, and the strategy flag only for squash/rebase.
    #[tokio::test]
    async fn mr_merge_builds_strategy_argv() {
        for (strategy, expected) in [
            (
                MergeStrategy::Merge,
                vec!["mr", "merge", "5", "--yes", "--auto-merge=false"],
            ),
            (
                MergeStrategy::Squash,
                vec![
                    "mr",
                    "merge",
                    "5",
                    "--yes",
                    "--auto-merge=false",
                    "--squash",
                ],
            ),
            (
                MergeStrategy::Rebase,
                vec![
                    "mr",
                    "merge",
                    "5",
                    "--yes",
                    "--auto-merge=false",
                    "--rebase",
                ],
            ),
        ] {
            let rec = RecordingRunner::replying(Reply::ok(""));
            let glab = GitLab::with_runner(&rec);
            glab.mr_merge(Path::new("/repo"), 5, strategy)
                .await
                .expect("mr_merge");
            assert_eq!(rec.only_call().args_str(), expected);
        }
    }

    // mr_ready maps to `mr update <id> --ready`; mr_close to `mr close <id>`.
    #[tokio::test]
    async fn mr_ready_and_close_build_expected_argv() {
        let rec = RecordingRunner::replying(Reply::ok(""));
        let glab = GitLab::with_runner(&rec);
        glab.mr_ready(Path::new("/repo"), 3).await.expect("ready");
        assert_eq!(rec.only_call().args_str(), ["mr", "update", "3", "--ready"]);

        let rec = RecordingRunner::replying(Reply::ok(""));
        let glab = GitLab::with_runner(&rec);
        glab.mr_close(Path::new("/repo"), 3).await.expect("close");
        assert_eq!(rec.only_call().args_str(), ["mr", "close", "3"]);
    }

    // mr_checks reads the MR's head_pipeline status and buckets it.
    #[tokio::test]
    async fn mr_checks_buckets_pipeline_status() {
        let json = r#"{"iid":4,"head_pipeline":{"status":"failed"}}"#;
        let glab = GitLab::with_runner(ScriptedRunner::new().on(["mr", "view"], Reply::ok(json)));
        assert_eq!(
            glab.mr_checks(Path::new("."), 4).await.unwrap(),
            CiStatus::Failing
        );
    }

    // issue_list builds the `--per-page 100 --output json` argv (per-page max
    // overrides glab's default page size of 30) and parses the JSON.
    #[tokio::test]
    async fn issue_list_builds_argv_and_parses() {
        let json = r#"[{"iid":3,"title":"Bug","state":"opened","description":"b","web_url":"u"}]"#;
        let rec = RecordingRunner::replying(Reply::ok(json));
        let glab = GitLab::with_runner(&rec);
        let issues = glab
            .issue_list(Path::new("/repo"))
            .await
            .expect("issue_list");
        assert_eq!(issues.len(), 1);
        assert_eq!(issues[0].number, 3);
        assert_eq!(issues[0].state, "opened");
        assert_eq!(
            rec.only_call().args_str(),
            ["issue", "list", "--per-page", "100", "--output", "json"]
        );
    }

    // issue_view builds `issue view <number> --output json` and parses the JSON.
    #[tokio::test]
    async fn issue_view_builds_argv_and_parses() {
        let json = r#"{"iid":7,"title":"T","state":"closed","description":"body","web_url":"https://gl/i/7"}"#;
        let rec = RecordingRunner::replying(Reply::ok(json));
        let glab = GitLab::with_runner(&rec);
        let issue = glab
            .issue_view(Path::new("/repo"), 7)
            .await
            .expect("issue_view");
        assert_eq!(issue.number, 7);
        assert_eq!(issue.body, "body");
        assert_eq!(issue.url, "https://gl/i/7");
        assert_eq!(
            rec.only_call().args_str(),
            ["issue", "view", "7", "--output", "json"]
        );
    }

    // issue_create assembles title/description/--yes and returns the trimmed
    // output (the issue URL).
    #[tokio::test]
    async fn issue_create_builds_argv_and_returns_url() {
        let rec = RecordingRunner::replying(Reply::ok("https://gl/i/9\n"));
        let glab = GitLab::with_runner(&rec);
        let url = glab
            .issue_create(Path::new("/repo"), "T", "B")
            .await
            .expect("issue_create");
        assert_eq!(url, "https://gl/i/9");
        assert_eq!(
            rec.only_call().args_str(),
            [
                "issue",
                "create",
                "--title",
                "T",
                "--description",
                "B",
                "--yes"
            ]
        );
    }

    // release_list builds the `--per-page 100 --output json` argv and parses the
    // JSON (URL comes off `_links.self`, date off `released_at`).
    #[tokio::test]
    async fn release_list_builds_argv_and_parses() {
        let json = r#"[{"tag_name":"v1.0","name":"Release 1.0","released_at":"2026-01-02T03:04:05.000Z","_links":{"self":"https://gl/-/releases/v1.0"}}]"#;
        let rec = RecordingRunner::replying(Reply::ok(json));
        let glab = GitLab::with_runner(&rec);
        let releases = glab
            .release_list(Path::new("/repo"))
            .await
            .expect("release_list");
        assert_eq!(releases.len(), 1);
        assert_eq!(releases[0].tag_name, "v1.0");
        assert_eq!(releases[0].url, "https://gl/-/releases/v1.0");
        assert_eq!(releases[0].published_at, "2026-01-02T03:04:05.000Z");
        assert_eq!(
            rec.only_call().args_str(),
            ["release", "list", "--per-page", "100", "--output", "json"]
        );
    }

    // release_view builds `release view <tag> --output json` and parses the JSON.
    #[tokio::test]
    async fn release_view_builds_argv_and_parses() {
        let json =
            r#"{"tag_name":"v2.1","name":"R","_links":{"self":"https://gl/-/releases/v2.1"}}"#;
        let rec = RecordingRunner::replying(Reply::ok(json));
        let glab = GitLab::with_runner(&rec);
        let rel = glab
            .release_view(Path::new("/repo"), "v2.1")
            .await
            .expect("release_view");
        assert_eq!(rel.tag_name, "v2.1");
        assert_eq!(rel.url, "https://gl/-/releases/v2.1");
        assert_eq!(
            rec.only_call().args_str(),
            ["release", "view", "v2.1", "--output", "json"]
        );
    }

    // release_view guards its bare `<tag>` positional: a flag-like or empty tag
    // is rejected before any process spawns.
    #[tokio::test]
    async fn release_view_rejects_flag_like_tag() {
        let glab = GitLab::with_runner(ScriptedRunner::new());
        assert!(glab.release_view(Path::new("."), "-evil").await.is_err());
        assert!(glab.release_view(Path::new("."), "").await.is_err());
    }

    // repo_view parses the GitLab Project JSON.
    #[tokio::test]
    async fn repo_view_parses_project() {
        let json = r#"{"name":"cli","path_with_namespace":"gitlab-org/cli","default_branch":"main","web_url":"u","visibility":"public"}"#;
        let glab = GitLab::with_runner(ScriptedRunner::new().on(["repo", "view"], Reply::ok(json)));
        let p = glab.repo_view(Path::new(".")).await.expect("repo_view");
        assert_eq!(p.path_with_namespace, "gitlab-org/cli");
        assert_eq!(p.default_branch, "main");
    }

    #[cfg(feature = "mock")]
    #[tokio::test]
    async fn consumer_mocks_the_interface() {
        let mut mock = MockGitLabApi::new();
        mock.expect_auth_status().returning(|| Ok(true));
        assert!(mock.auth_status().await.unwrap());
    }
}

// Long-form how-to guides, rendered from this crate's docs/*.md on docs.rs.
#[doc = include_str!("../docs/gitlab.md")]
#[allow(rustdoc::broken_intra_doc_links)]
pub mod guide {}