gitflow-gitlab 1.2.0

gf 的 GitLab 适配器,基于 glab CLI 提供 Issue/MR/Release/Review 等能力。GitLab adapter for gf via glab CLI.
Documentation
//! Command execution abstraction for GitLab CLI (`glab`).
//!
//! This module provides the [`CommandRunner`] trait and its implementations,
//! allowing the GitLab crate to spawn CLI processes in production and inject
//! controlled outputs in tests.

use std::process::ExitStatus;

/// Output from a CLI command execution.
#[derive(Debug, Clone)]
pub struct CommandOutput {
    /// Process exit status.
    pub status: ExitStatus,
    /// Standard output bytes.
    pub stdout: Vec<u8>,
    /// Standard error bytes.
    pub stderr: Vec<u8>,
}

/// Trait for executing CLI commands. Abstracts process spawning for testability.
#[async_trait::async_trait]
pub trait CommandRunner: std::fmt::Debug + Send + Sync {
    /// Execute a command with the given program and arguments.
    ///
    /// # Errors
    ///
    /// Returns [`std::io::Error`] if the command cannot be spawned.
    async fn run(&self, program: &str, args: &[&str]) -> std::io::Result<CommandOutput>;

    /// Execute a command with the given program and arguments, writing
    /// `stdin_data` to the child process's standard input.
    ///
    /// This avoids exposing sensitive values (such as tokens) in process
    /// arguments, where they would be visible to other users via `ps`.
    ///
    /// # Errors
    ///
    /// Returns [`std::io::Error`] if the command cannot be spawned or if
    /// writing to its standard input fails.
    async fn run_with_stdin(
        &self,
        program: &str,
        args: &[&str],
        stdin_data: &[u8],
    ) -> std::io::Result<CommandOutput>;
}

/// Default implementation that spawns real processes via [`tokio::process::Command`].
#[derive(Debug, Clone, Default)]
pub struct RealCommandRunner;

#[async_trait::async_trait]
impl CommandRunner for RealCommandRunner {
    async fn run(&self, program: &str, args: &[&str]) -> std::io::Result<CommandOutput> {
        let output = tokio::process::Command::new(program)
            .args(args)
            .output()
            .await?;
        Ok(CommandOutput {
            status: output.status,
            stdout: output.stdout,
            stderr: output.stderr,
        })
    }

    async fn run_with_stdin(
        &self,
        program: &str,
        args: &[&str],
        stdin_data: &[u8],
    ) -> std::io::Result<CommandOutput> {
        use tokio::io::AsyncWriteExt;

        let mut child = tokio::process::Command::new(program)
            .args(args)
            .stdin(std::process::Stdio::piped())
            .stdout(std::process::Stdio::piped())
            .stderr(std::process::Stdio::piped())
            .spawn()?;

        if let Some(mut stdin) = child.stdin.take() {
            stdin.write_all(stdin_data).await?;
            drop(stdin);
        }

        let output = child.wait_with_output().await?;
        Ok(CommandOutput {
            status: output.status,
            stdout: output.stdout,
            stderr: output.stderr,
        })
    }
}

/// Mock implementation for testing failure scenarios.
///
/// Stores either a success output or an error kind with a message,
/// enabling `Clone` without requiring [`std::io::Error`] itself to be cloneable.
#[cfg(test)]
#[derive(Debug, Clone)]
pub struct MockCommandRunner {
    result: MockResult,
}

#[cfg(test)]
#[derive(Debug, Clone)]
enum MockResult {
    /// Successful command output.
    Output(CommandOutput),
    /// Spawn error with kind and message.
    Error(std::io::ErrorKind, String),
}

#[cfg(test)]
impl MockCommandRunner {
    #[cfg(unix)]
    pub(crate) fn make_exit_status(code: i32) -> ExitStatus {
        use std::os::unix::process::ExitStatusExt;
        ExitStatus::from_raw(code)
    }

    #[cfg(windows)]
    pub(crate) fn make_exit_status(code: i32) -> ExitStatus {
        use std::os::windows::process::ExitStatusExt;
        // Exit codes are conventionally non-negative; clamp negatives to 1.
        let raw = u32::try_from(code).unwrap_or(1);
        ExitStatus::from_raw(raw)
    }

    /// Create a mock that returns success with the given stdout.
    #[must_use]
    pub fn success(stdout: &str) -> Self {
        Self {
            result: MockResult::Output(CommandOutput {
                status: Self::make_exit_status(0),
                stdout: stdout.as_bytes().to_vec(),
                stderr: Vec::new(),
            }),
        }
    }

    /// Create a mock that returns failure with the given stderr and exit code.
    #[must_use]
    pub fn failure(stderr: &str, code: i32) -> Self {
        Self {
            result: MockResult::Output(CommandOutput {
                status: Self::make_exit_status(code),
                stdout: Vec::new(),
                stderr: stderr.as_bytes().to_vec(),
            }),
        }
    }

    /// Create a mock that returns a spawn error.
    #[must_use]
    pub fn spawn_error() -> Self {
        Self {
            result: MockResult::Error(std::io::ErrorKind::NotFound, "command not found".to_owned()),
        }
    }
}

#[cfg(test)]
#[async_trait::async_trait]
impl CommandRunner for MockCommandRunner {
    async fn run(&self, _program: &str, _args: &[&str]) -> std::io::Result<CommandOutput> {
        match &self.result {
            MockResult::Output(output) => Ok(output.clone()),
            MockResult::Error(kind, message) => Err(std::io::Error::new(*kind, message.clone())),
        }
    }

    async fn run_with_stdin(
        &self,
        program: &str,
        args: &[&str],
        _stdin_data: &[u8],
    ) -> std::io::Result<CommandOutput> {
        self.run(program, args).await
    }
}

/// Mock implementation that returns a sequence of preconfigured responses.
///
/// Each call to [`CommandRunner::run`] pops the next response from the queue.
/// Useful for testing retry logic where different commands must succeed or fail
/// in a specific order (e.g., `add_labels` retries after auto-creating a label).
#[cfg(test)]
#[derive(Debug, Clone)]
pub struct SequencedMockCommandRunner {
    responses: std::sync::Arc<std::sync::Mutex<std::collections::VecDeque<CommandOutput>>>,
}

#[cfg(test)]
impl SequencedMockCommandRunner {
    /// Build a runner that yields `outputs` in order, one per `run` call.
    #[must_use]
    pub fn new(outputs: Vec<CommandOutput>) -> Self {
        Self {
            responses: std::sync::Arc::new(std::sync::Mutex::new(outputs.into())),
        }
    }

    /// Convenience: build a sequence from `(success, stdout_or_stderr)` tuples.
    ///
    /// When `success` is `true`, the string is used as stdout with exit code 0.
    /// When `false`, it is used as stderr with exit code 1.
    #[must_use]
    pub fn from_results(results: &[(bool, &str)]) -> Self {
        let outputs = results
            .iter()
            .map(|&(ok, text)| {
                if ok {
                    CommandOutput {
                        status: MockCommandRunner::make_exit_status(0),
                        stdout: text.as_bytes().to_vec(),
                        stderr: Vec::new(),
                    }
                } else {
                    CommandOutput {
                        status: MockCommandRunner::make_exit_status(1),
                        stdout: Vec::new(),
                        stderr: text.as_bytes().to_vec(),
                    }
                }
            })
            .collect();
        Self::new(outputs)
    }
}

#[cfg(test)]
#[async_trait::async_trait]
impl CommandRunner for SequencedMockCommandRunner {
    async fn run(&self, _program: &str, _args: &[&str]) -> std::io::Result<CommandOutput> {
        let mut guard = self
            .responses
            .lock()
            .expect("SequencedMockCommandRunner mutex poisoned");
        guard
            .pop_front()
            .ok_or_else(|| std::io::Error::other("no more responses"))
    }

    async fn run_with_stdin(
        &self,
        program: &str,
        args: &[&str],
        _stdin_data: &[u8],
    ) -> std::io::Result<CommandOutput> {
        self.run(program, args).await
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[tokio::test]
    async fn test_should_return_success_output_from_mock() {
        let runner = MockCommandRunner::success("hello");
        let output = runner
            .run("glab", &["--version"])
            .await
            .expect("should succeed");
        assert!(output.status.success());
        assert_eq!(output.stdout, b"hello");
        assert!(output.stderr.is_empty());
    }

    #[tokio::test]
    async fn test_should_return_failure_output_from_mock() {
        let runner = MockCommandRunner::failure("not found", 1);
        let output = runner
            .run("glab", &["repo", "view"])
            .await
            .expect("should succeed");
        assert!(!output.status.success());
        assert!(output.stdout.is_empty());
        assert_eq!(output.stderr, b"not found");
    }

    #[tokio::test]
    async fn test_should_return_spawn_error_from_mock() {
        let runner = MockCommandRunner::spawn_error();
        let err = runner
            .run("glab", &["--version"])
            .await
            .expect_err("should fail");
        assert_eq!(err.kind(), std::io::ErrorKind::NotFound);
    }

    #[tokio::test]
    async fn test_should_clone_command_output() {
        let runner = MockCommandRunner::success("data");
        let output = runner.run("glab", &[]).await.expect("should succeed");
        let cloned = output.clone();
        assert_eq!(output.stdout, cloned.stdout);
        assert_eq!(output.stderr, cloned.stderr);
    }

    #[tokio::test]
    async fn test_should_clone_mock_runner() {
        let runner = MockCommandRunner::success("cloneable");
        let cloned = runner.clone();
        let output = cloned.run("glab", &[]).await.expect("should succeed");
        assert_eq!(output.stdout, b"cloneable");
    }

    #[tokio::test]
    async fn test_should_yield_sequenced_responses() {
        let runner = SequencedMockCommandRunner::from_results(&[
            (true, "first"),
            (false, "error"),
            (true, "third"),
        ]);

        let out1 = runner.run("glab", &[]).await.expect("first should succeed");
        assert!(out1.status.success());
        assert_eq!(out1.stdout, b"first");

        let out2 = runner
            .run("glab", &[])
            .await
            .expect("second should 'succeed' as Output");
        assert!(!out2.status.success());
        assert_eq!(out2.stderr, b"error");

        let out3 = runner.run("glab", &[]).await.expect("third should succeed");
        assert_eq!(out3.stdout, b"third");
    }

    #[tokio::test]
    async fn test_should_error_when_sequence_exhausted() {
        let runner = SequencedMockCommandRunner::from_results(&[(true, "only")]);

        let _ = runner.run("glab", &[]).await.expect("first call");
        let err = runner.run("glab", &[]).await.expect_err("exhausted");
        assert_eq!(err.kind(), std::io::ErrorKind::Other);
    }
}