loaders 0.0.0

//! Terminal capability detection implemented with the Rust standard library.

use std::env;

/// The detected terminal capabilities for a stream.
///
/// Use this when choosing whether to emit ANSI control sequences, how wide a
/// progress bar should be, or whether output is likely running in CI.
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct TerminalInfo {
    /// Whether the file descriptor appears to be a TTY.
    pub is_tty: bool,
    /// The detected terminal width in columns.
    pub width: usize,
    /// The detected terminal height in rows.
    pub height: usize,
    /// The best detected color capability.
    pub color_support: ColorSupport,
    /// Whether common CI environment variables are present.
    pub is_ci: bool,
}

/// Terminal color support level.
///
/// The value is inferred from `NO_COLOR`, `COLORTERM`, `TERM_PROGRAM`, `TERM`,
/// and common CI environment variables.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum ColorSupport {
    /// ANSI colors should not be emitted.
    None,
    /// Basic sixteen-color ANSI support.
    Ansi16,
    /// ANSI 256-color support.
    Ansi256,
    /// ANSI true-color support.
    TrueColor,
}

impl TerminalInfo {
    /// Detects terminal information for standard output.
    ///
    /// # Examples
    ///
    /// ```rust
    /// let info = loaders::terminal::detect::TerminalInfo::detect();
    /// assert!(info.width > 0);
    /// ```
    pub fn detect() -> Self {
        Self::detect_for_fd(1)
    }

    /// Detects terminal information for a numeric file descriptor.
    ///
    /// # Examples
    ///
    /// ```rust
    /// let info = loaders::terminal::detect::TerminalInfo::detect_for_fd(1);
    /// assert!(info.height > 0);
    /// ```
    pub fn detect_for_fd(fd: i32) -> Self {
        Self {
            is_tty: is_tty(fd),
            width: terminal_width_for_fd(fd),
            height: terminal_height_for_fd(fd),
            color_support: color_support(),
            is_ci: is_ci_environment(),
        }
    }
}

/// Returns the detected terminal width, falling back to `80`.
///
/// # Examples
///
/// ```rust
/// assert!(loaders::terminal::detect::terminal_width() > 0);
/// ```
pub fn terminal_width() -> usize {
    terminal_width_for_fd(1)
}

/// Returns the detected terminal width for a file descriptor, falling back to
/// `80`.
///
/// # Examples
///
/// ```rust
/// assert!(loaders::terminal::detect::terminal_width_for_fd(1) > 0);
/// ```
pub fn terminal_width_for_fd(fd: i32) -> usize {
    if let Some(width) = env_usize("COLUMNS") {
        return width.max(1);
    }

    #[cfg(unix)]
    {
        if let Some(width) = unix_terminal_size(fd).map(|(w, _)| w) {
            return width.max(1);
        }
    }

    #[cfg(windows)]
    {
        if let Some((width, _)) = windows_terminal_size(fd) {
            return width.max(1);
        }
    }

    80
}

/// Returns the detected terminal height, falling back to `24`.
///
/// # Examples
///
/// ```rust
/// assert!(loaders::terminal::detect::terminal_height() > 0);
/// ```
pub fn terminal_height() -> usize {
    terminal_height_for_fd(1)
}

/// Returns the detected terminal height for a file descriptor, falling back to
/// `24`.
///
/// # Examples
///
/// ```rust
/// assert!(loaders::terminal::detect::terminal_height_for_fd(1) > 0);
/// ```
pub fn terminal_height_for_fd(fd: i32) -> usize {
    if let Some(height) = env_usize("LINES") {
        return height.max(1);
    }

    #[cfg(unix)]
    {
        if let Some(height) = unix_terminal_size(fd).map(|(_, h)| h) {
            return height.max(1);
        }
    }

    #[cfg(windows)]
    {
        if let Some((_, height)) = windows_terminal_size(fd) {
            return height.max(1);
        }
    }

    24
}

/// Returns whether a file descriptor is attached to a terminal.
///
/// # Examples
///
/// ```rust
/// let _ = loaders::terminal::detect::is_tty(1);
/// ```
#[cfg(unix)]
pub fn is_tty(fd: i32) -> bool {
    unsafe extern "C" {
        fn isatty(fd: std::os::raw::c_int) -> std::os::raw::c_int;
    }

    // SAFETY: `isatty` does not take ownership of the descriptor and is safe to
    // call with any integer file descriptor value.
    unsafe { isatty(fd as std::os::raw::c_int) == 1 }
}

/// Returns whether a file descriptor is attached to a terminal.
///
/// Uses Win32 console mode checks while keeping the crate dependency-free.
#[cfg(windows)]
pub fn is_tty(fd: i32) -> bool {
    let Some(handle) = windows_output_handle(fd) else {
        return false;
    };
    console_mode(handle).is_some()
}

/// Returns whether a stream supports interactive cursor-based rendering.
///
/// On Windows this also enables virtual terminal processing when available so
/// ANSI cursor controls can update progress on the same line.
#[cfg(unix)]
pub fn supports_interactive_output(fd: i32) -> bool {
    is_tty(fd)
}

/// Returns whether a stream supports interactive cursor-based rendering.
///
/// On Windows this also enables virtual terminal processing when available so
/// ANSI cursor controls can update progress on the same line.
#[cfg(windows)]
pub fn supports_interactive_output(fd: i32) -> bool {
    let Some(handle) = windows_output_handle(fd) else {
        return false;
    };
    let Some(mode) = console_mode(handle) else {
        return false;
    };

    const ENABLE_VIRTUAL_TERMINAL_PROCESSING: u32 = 0x0004;
    if mode & ENABLE_VIRTUAL_TERMINAL_PROCESSING != 0 {
        return true;
    }

    // SAFETY: `handle` was retrieved from `GetStdHandle` and remains owned by
    // the process. `SetConsoleMode` updates console flags in place.
    unsafe { set_console_mode(handle, mode | ENABLE_VIRTUAL_TERMINAL_PROCESSING) != 0 }
}

/// Returns true when common CI environment variables are present.
///
/// # Examples
///
/// ```rust
/// let _ = loaders::terminal::detect::is_ci_environment();
/// ```
pub fn is_ci_environment() -> bool {
    [
        "CI",
        "GITHUB_ACTIONS",
        "GITLAB_CI",
        "CIRCLECI",
        "TRAVIS",
        "JENKINS_URL",
        "BUILDKITE",
        "TF_BUILD",
        "TEAMCITY_VERSION",
    ]
    .iter()
    .any(|key| env::var_os(key).is_some())
}

/// Detects color support from standard terminal environment variables.
///
/// # Examples
///
/// ```rust
/// let _support = loaders::terminal::detect::color_support();
/// ```
pub fn color_support() -> ColorSupport {
    if env::var_os("NO_COLOR").is_some() {
        return ColorSupport::None;
    }

    if let Ok(colorterm) = env::var("COLORTERM") {
        let lower = colorterm.to_ascii_lowercase();
        if lower == "truecolor" || lower == "24bit" {
            return ColorSupport::TrueColor;
        }
    }

    if let Ok(program) = env::var("TERM_PROGRAM")
        && (program == "iTerm.app" || program == "Hyper")
    {
        return ColorSupport::TrueColor;
    }

    if let Ok(term) = env::var("TERM") {
        let lower = term.to_ascii_lowercase();
        if lower.contains("256color") {
            return ColorSupport::Ansi256;
        }
        if lower.contains("xterm") || lower.contains("ansi") || lower.contains("screen") {
            return ColorSupport::Ansi16;
        }
        if lower == "dumb" {
            return ColorSupport::None;
        }
    }

    if is_ci_environment() {
        ColorSupport::None
    } else {
        ColorSupport::Ansi16
    }
}

fn env_usize(key: &str) -> Option<usize> {
    env::var(key)
        .ok()
        .and_then(|value| value.parse::<usize>().ok())
}

#[cfg(windows)]
type Handle = *mut std::ffi::c_void;

#[cfg(windows)]
const STD_OUTPUT_HANDLE: u32 = -11i32 as u32;
#[cfg(windows)]
const STD_ERROR_HANDLE: u32 = -12i32 as u32;
#[cfg(windows)]
const INVALID_HANDLE_VALUE: Handle = -1isize as Handle;

#[cfg(windows)]
fn windows_output_handle(fd: i32) -> Option<Handle> {
    let std_handle = match fd {
        1 => STD_OUTPUT_HANDLE,
        2 => STD_ERROR_HANDLE,
        _ => return None,
    };

    // SAFETY: `GetStdHandle` reads process-owned standard handles and does not
    // take ownership.
    let handle = unsafe { get_std_handle(std_handle) };
    if handle.is_null() || handle == INVALID_HANDLE_VALUE {
        return None;
    }
    Some(handle)
}

#[cfg(windows)]
fn console_mode(handle: Handle) -> Option<u32> {
    let mut mode = 0u32;
    // SAFETY: `handle` is expected to be a valid console handle and `mode`
    // points to writable memory for the duration of the call.
    let ok = unsafe { get_console_mode(handle, &mut mode) };
    if ok == 0 { None } else { Some(mode) }
}

#[cfg(windows)]
fn windows_terminal_size(fd: i32) -> Option<(usize, usize)> {
    let handle = windows_output_handle(fd)?;
    let info = console_screen_buffer_info(handle)?;
    let width = i32::from(info.sr_window.right) - i32::from(info.sr_window.left) + 1;
    let height = i32::from(info.sr_window.bottom) - i32::from(info.sr_window.top) + 1;
    if width > 0 && height > 0 {
        Some((width as usize, height as usize))
    } else {
        None
    }
}

#[cfg(windows)]
fn console_screen_buffer_info(handle: Handle) -> Option<ConsoleScreenBufferInfo> {
    let mut info = ConsoleScreenBufferInfo::default();
    // SAFETY: `handle` is expected to be a valid console handle and `info`
    // points to writable memory for the duration of the call.
    let ok = unsafe { get_console_screen_buffer_info(handle, &mut info) };
    if ok == 0 { None } else { Some(info) }
}

#[cfg(windows)]
#[derive(Clone, Copy, Default)]
#[repr(C)]
struct Coord {
    x: i16,
    y: i16,
}

#[cfg(windows)]
#[derive(Clone, Copy, Default)]
#[repr(C)]
struct SmallRect {
    left: i16,
    top: i16,
    right: i16,
    bottom: i16,
}

#[cfg(windows)]
#[derive(Clone, Copy, Default)]
#[repr(C)]
struct ConsoleScreenBufferInfo {
    dw_size: Coord,
    dw_cursor_position: Coord,
    w_attributes: u16,
    sr_window: SmallRect,
    dw_maximum_window_size: Coord,
}

#[cfg(windows)]
unsafe fn get_std_handle(std_handle: u32) -> Handle {
    unsafe extern "system" {
        fn GetStdHandle(nStdHandle: u32) -> Handle;
    }
    // SAFETY: delegated to Win32 API contract.
    unsafe { GetStdHandle(std_handle) }
}

#[cfg(windows)]
unsafe fn get_console_mode(handle: Handle, mode: *mut u32) -> i32 {
    unsafe extern "system" {
        fn GetConsoleMode(hConsoleHandle: Handle, lpMode: *mut u32) -> i32;
    }
    // SAFETY: delegated to Win32 API contract.
    unsafe { GetConsoleMode(handle, mode) }
}

#[cfg(windows)]
unsafe fn set_console_mode(handle: Handle, mode: u32) -> i32 {
    unsafe extern "system" {
        fn SetConsoleMode(hConsoleHandle: Handle, dwMode: u32) -> i32;
    }
    // SAFETY: delegated to Win32 API contract.
    unsafe { SetConsoleMode(handle, mode) }
}

#[cfg(windows)]
unsafe fn get_console_screen_buffer_info(
    handle: Handle,
    info: *mut ConsoleScreenBufferInfo,
) -> i32 {
    unsafe extern "system" {
        fn GetConsoleScreenBufferInfo(
            hConsoleOutput: Handle,
            lpConsoleScreenBufferInfo: *mut ConsoleScreenBufferInfo,
        ) -> i32;
    }
    // SAFETY: delegated to Win32 API contract.
    unsafe { GetConsoleScreenBufferInfo(handle, info) }
}

#[cfg(unix)]
fn unix_terminal_size(fd: i32) -> Option<(usize, usize)> {
    #[repr(C)]
    struct WinSize {
        ws_row: u16,
        ws_col: u16,
        ws_xpixel: u16,
        ws_ypixel: u16,
    }

    unsafe extern "C" {
        fn ioctl(
            fd: std::os::raw::c_int,
            request: std::os::raw::c_ulong,
            ...
        ) -> std::os::raw::c_int;
    }

    #[cfg(any(target_os = "linux", target_os = "android"))]
    const TIOCGWINSZ: std::os::raw::c_ulong = 0x5413;
    #[cfg(any(target_os = "macos", target_os = "ios", target_os = "freebsd"))]
    const TIOCGWINSZ: std::os::raw::c_ulong = 0x4008_7468;
    #[cfg(not(any(
        target_os = "linux",
        target_os = "android",
        target_os = "macos",
        target_os = "ios",
        target_os = "freebsd"
    )))]
    const TIOCGWINSZ: std::os::raw::c_ulong = 0;

    if TIOCGWINSZ == 0 {
        return None;
    }

    let mut size = WinSize {
        ws_row: 0,
        ws_col: 0,
        ws_xpixel: 0,
        ws_ypixel: 0,
    };

    // SAFETY: `ioctl` writes into a properly aligned `WinSize` value owned by
    // this function and does not retain the pointer after returning.
    let result = unsafe { ioctl(fd as std::os::raw::c_int, TIOCGWINSZ, &mut size) };
    if result == 0 && size.ws_col > 0 && size.ws_row > 0 {
        Some((usize::from(size.ws_col), usize::from(size.ws_row)))
    } else {
        None
    }
}

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

    static ENV_LOCK: Mutex<()> = Mutex::new(());

    fn with_env_lock(f: impl FnOnce()) {
        match ENV_LOCK.lock() {
            Ok(_guard) => f(),
            Err(poisoned) => {
                let _guard = poisoned.into_inner();
                f();
            }
        }
    }

    #[test]
    fn test_ci_detection_github_actions() {
        with_env_lock(|| {
            unsafe {
                env::set_var("GITHUB_ACTIONS", "true");
            }
            assert!(is_ci_environment());
            unsafe {
                env::remove_var("GITHUB_ACTIONS");
            }
        });
    }

    #[test]
    fn test_ci_detection_gitlab() {
        with_env_lock(|| {
            unsafe {
                env::set_var("GITLAB_CI", "true");
            }
            assert!(is_ci_environment());
            unsafe {
                env::remove_var("GITLAB_CI");
            }
        });
    }

    #[test]
    fn test_no_color_env() {
        with_env_lock(|| {
            unsafe {
                env::set_var("NO_COLOR", "1");
            }
            assert_eq!(color_support(), ColorSupport::None);
            unsafe {
                env::remove_var("NO_COLOR");
            }
        });
    }

    #[test]
    fn test_truecolor_detection() {
        with_env_lock(|| {
            unsafe {
                env::remove_var("NO_COLOR");
                env::set_var("COLORTERM", "truecolor");
            }
            assert_eq!(color_support(), ColorSupport::TrueColor);
            unsafe {
                env::remove_var("COLORTERM");
            }
        });
    }

    #[test]
    fn test_256_color_detection() {
        with_env_lock(|| {
            unsafe {
                env::remove_var("NO_COLOR");
                env::remove_var("COLORTERM");
                env::set_var("TERM", "xterm-256color");
            }
            assert_eq!(color_support(), ColorSupport::Ansi256);
            unsafe {
                env::remove_var("TERM");
            }
        });
    }

    #[test]
    fn test_fallback_width_is_80() {
        with_env_lock(|| {
            unsafe {
                env::remove_var("COLUMNS");
            }
            let width = terminal_width();
            assert!(width == 80 || width > 0);
        });
    }

    #[test]
    fn test_columns_env_var_respected() {
        with_env_lock(|| {
            unsafe {
                env::set_var("COLUMNS", "123");
            }
            assert_eq!(terminal_width(), 123);
            assert_eq!(terminal_width_for_fd(2), 123);
            unsafe {
                env::remove_var("COLUMNS");
            }
        });
    }

    #[test]
    fn test_invalid_fd_not_interactive() {
        assert!(!is_tty(-1));
        assert!(!supports_interactive_output(-1));
        assert!(terminal_width_for_fd(-1) > 0);
        assert!(terminal_height_for_fd(-1) > 0);
    }
}