feat(system): represent the host OS as a typed Os enum with per-executor support gates

Replaces the loose `os` + `os_version` strings on `SystemInfo` with an `Os`
enum (`SupportedLinux { distro, version }`, `OtherLinux`, `MacOs`,
`Unsupported`) and the global `SUPPORTED_SYSTEMS` tuple lookup with a single
`match` in `check_system`. Adds `Executor::support_level(&Os)` so each executor
declares its own OS matrix: `run_executor` bails on `Unsupported`, skips
`setup()` on `RequiresManualSetup`, and runs it on `FullySupported`. This
removes the dirty macOS best-effort branch previously living in `check.rs`.

The wire format is preserved: `Os` serializes via an `OsSerde` shim and is
flattened into `SystemInfo` via `#[serde(flatten)]`, so the JSON sent to the
API is byte-identical (verified by the existing upload-metadata snapshot
tests).

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: GuillaumeLagrange

src/cli/setup.rs

@@ -1,4 +1,4 @@
-use crate::executor::{ToolInstallStatus, get_all_executors};
+use crate::executor::{ExecutorSupport, ToolInstallStatus, get_all_executors};
 use crate::prelude::*;
 use crate::system::SystemInfo;
 use clap::{Args, Subcommand};
@@ -22,10 +22,7 @@ enum SetupCommands {
 pub async fn run(args: SetupArgs, setup_cache_dir: Option<&Path>) -> Result<()> {
     match args.command {
         None => setup(setup_cache_dir).await,
-        Some(SetupCommands::Status) => {
-            status();
-            Ok(())
-        }
+        Some(SetupCommands::Status) => status(),
     }
 }
 
@@ -34,20 +31,43 @@ async fn setup(setup_cache_dir: Option<&Path>) -> Result<()> {
     let executors = get_all_executors();
     start_group!("Setting up the environment for all executors");
     for executor in executors {
-        info!(
-            "Setting up the environment for the executor: {}",
-            executor.name()
-        );
-        executor.setup(&system_info, setup_cache_dir).await?;
+        match executor.support_level(&system_info.os) {
+            ExecutorSupport::Unsupported => {
+                info!(
+                    "Skipping setup for the {} executor: not supported on {}",
+                    executor.name(),
+                    system_info.os
+                );
+            }
+            ExecutorSupport::RequiresManualSetup => {
+                info!(
+                    "Skipping automatic setup for the {} executor on {}; install required tooling manually.",
+                    executor.name(),
+                    system_info.os
+                );
+            }
+            ExecutorSupport::FullySupported => {
+                info!(
+                    "Setting up the environment for the executor: {}",
+                    executor.name()
+                );
+                executor.setup(&system_info, setup_cache_dir).await?;
+            }
+        }
     }
     info!("Environment setup completed");
     end_group!();
     Ok(())
 }
 
-pub fn status() {
+pub fn status() -> Result<()> {
+    let system_info = SystemInfo::new()?;
     info!("{}", style("Tools").bold());
     for executor in get_all_executors() {
+        // Don't probe for tooling that can't be used on this OS anyway.
+        if executor.support_level(&system_info.os) == ExecutorSupport::Unsupported {
+            continue;
+        }
         let tool_status = executor.tool_status();
         match &tool_status.status {
             ToolInstallStatus::Installed { version } => {
@@ -71,4 +91,5 @@ pub fn status() {
             }
         }
     }
+    Ok(())
 }

src/cli/status.rs

@@ -22,17 +22,14 @@ pub async fn run(api_client: &CodSpeedAPIClient) -> Result<()> {
     info!("");
 
     // Setup/tools status
-    super::setup::status();
+    super::setup::status()?;
     info!("");
 
     // System info
     info!("{}", style("System").bold());
     info!("  codspeed {VERSION}");
     let system_info = SystemInfo::new()?;
-    info!(
-        "  {} {} ({})",
-        system_info.os, system_info.os_version, system_info.arch
-    );
+    info!("  {} ({})", system_info.os, system_info.arch);
     info!(
         "  {} ({}C / {}GB)",
         system_info.cpu_brand, system_info.cpu_cores, system_info.total_memory_gb

src/executor/helpers/apt.rs

@@ -1,13 +1,13 @@
 use super::run_with_sudo::run_with_sudo;
 use crate::prelude::*;
-use crate::system::SystemInfo;
+use crate::system::{Os, SystemInfo};
 use std::path::Path;
 use std::process::Command;
 
 const METADATA_FILENAME: &str = "./tmp/codspeed-cache-metadata.txt";
 
 fn is_system_compatible(system_info: &SystemInfo) -> bool {
-    system_info.os == "ubuntu" || system_info.os == "debian"
+    matches!(system_info.os, Os::SupportedLinux { .. })
 }
 
 /// Installs packages with caching support.

src/executor/memory/executor.rs

@@ -1,4 +1,5 @@
 use crate::executor::ExecutorName;
+use crate::executor::ExecutorSupport;
 use crate::executor::ToolStatus;
 use crate::executor::helpers::command::CommandBuilder;
 use crate::executor::helpers::env::get_base_injected_env;
@@ -11,7 +12,7 @@ use crate::executor::{ExecutionContext, Executor};
 use crate::instruments::mongo_tracer::MongoTracer;
 use crate::prelude::*;
 use crate::runner_mode::RunnerMode;
-use crate::system::SystemInfo;
+use crate::system::{Os, SystemInfo};
 use async_trait::async_trait;
 use ipc_channel::ipc;
 use memtrack::MemtrackIpcClient;
@@ -76,6 +77,14 @@ impl Executor for MemoryExecutor {
         get_memtrack_status()
     }
 
+    fn support_level(&self, os: &Os) -> ExecutorSupport {
+        match os {
+            Os::SupportedLinux { .. } => ExecutorSupport::FullySupported,
+            Os::OtherLinux { .. } => ExecutorSupport::RequiresManualSetup,
+            Os::MacOs { .. } | Os::Unsupported { .. } => ExecutorSupport::Unsupported,
+        }
+    }
+
     async fn setup(
         &self,
         _system_info: &SystemInfo,

src/executor/mod.rs

@@ -15,7 +15,7 @@ mod wall_time;
 use crate::instruments::mongo_tracer::{MongoTracer, install_mongodb_tracer};
 use crate::prelude::*;
 use crate::runner_mode::RunnerMode;
-use crate::system::SystemInfo;
+use crate::system::{Os, SystemInfo};
 use async_trait::async_trait;
 pub use config::{BenchmarkTarget, ExecutorConfig, OrchestratorConfig};
 pub use execution_context::ExecutionContext;
@@ -73,13 +73,30 @@ pub enum ToolInstallStatus {
     NotInstalled,
 }
 
+/// How well a given executor runs on a given [`Os`].
+#[derive(Debug, Eq, PartialEq, Clone, Copy)]
+pub enum ExecutorSupport {
+    /// The executor cannot run on this OS at all — `run_executor` hard-bails.
+    Unsupported,
+    /// The executor runs on this OS, but the user is responsible for installing the required
+    /// tooling themselves; `setup()` is skipped.
+    RequiresManualSetup,
+    /// The executor runs on this OS and `setup()` knows how to auto-install tooling.
+    FullySupported,
+}
+
 #[async_trait(?Send)]
 pub trait Executor {
     fn name(&self) -> ExecutorName;
 
     /// Report the installation status of the tool(s) this executor depends on.
     fn tool_status(&self) -> ToolStatus;
 
+    /// Declare how well this executor runs on the host OS. Drives whether `setup()` is invoked
+    /// (only when [`ExecutorSupport::FullySupported`]) and whether we bail out of running the
+    /// executor at all (on [`ExecutorSupport::Unsupported`]).
+    fn support_level(&self, os: &Os) -> ExecutorSupport;
+
     async fn setup(
         &self,
         _system_info: &SystemInfo,
@@ -107,11 +124,33 @@ pub async fn run_executor(
     execution_context: &ExecutionContext,
     setup_cache_dir: Option<&Path>,
 ) -> Result<()> {
-    if !execution_context.config.skip_setup {
-        executor
-            .setup(&orchestrator.system_info, setup_cache_dir)
-            .await?;
+    match executor.support_level(&orchestrator.system_info.os) {
+        ExecutorSupport::Unsupported => {
+            bail!(
+                "The {} executor is not supported on {}",
+                executor.name(),
+                orchestrator.system_info.os
+            );
+        }
+        ExecutorSupport::RequiresManualSetup => {
+            if !execution_context.config.skip_setup {
+                info!(
+                    "Skipping automatic setup for the {} executor on {}; ensure required tooling is installed manually.",
+                    executor.name(),
+                    orchestrator.system_info.os
+                );
+            }
+        }
+        ExecutorSupport::FullySupported => {
+            if !execution_context.config.skip_setup {
+                executor
+                    .setup(&orchestrator.system_info, setup_cache_dir)
+                    .await?;
+            }
+        }
+    }
 
+    if !execution_context.config.skip_setup {
         // TODO: refactor and move directly in the Instruments struct as a `setup` method
         if execution_context.config.instruments.is_mongodb_enabled() {
             install_mongodb_tracer().await?;

src/executor/valgrind/executor.rs

@@ -3,10 +3,10 @@ use std::path::Path;
 
 use crate::executor::Executor;
 use crate::executor::ToolStatus;
-use crate::executor::{ExecutionContext, ExecutorName};
+use crate::executor::{ExecutionContext, ExecutorName, ExecutorSupport};
 use crate::instruments::mongo_tracer::MongoTracer;
 use crate::prelude::*;
-use crate::system::SystemInfo;
+use crate::system::{Os, SystemInfo};
 
 use super::setup::{get_valgrind_status, install_valgrind};
 use super::{helpers::perf_maps::harvest_perf_maps, helpers::venv_compat, measure};
@@ -23,6 +23,14 @@ impl Executor for ValgrindExecutor {
         get_valgrind_status()
     }
 
+    fn support_level(&self, os: &Os) -> ExecutorSupport {
+        match os {
+            Os::SupportedLinux { .. } => ExecutorSupport::FullySupported,
+            Os::OtherLinux { .. } => ExecutorSupport::RequiresManualSetup,
+            Os::MacOs { .. } | Os::Unsupported { .. } => ExecutorSupport::Unsupported,
+        }
+    }
+
     async fn setup(&self, system_info: &SystemInfo, setup_cache_dir: Option<&Path>) -> Result<()> {
         install_valgrind(system_info, setup_cache_dir).await?;
 

src/executor/valgrind/setup.rs

@@ -2,7 +2,7 @@ use crate::cli::run::helpers::download_file;
 use crate::executor::helpers::apt;
 use crate::executor::{ToolInstallStatus, ToolStatus};
 use crate::prelude::*;
-use crate::system::SystemInfo;
+use crate::system::{Os, SupportedLinuxDistro, SystemInfo};
 use crate::{
     VALGRIND_CODSPEED_DEB_VERSION, VALGRIND_CODSPEED_VERSION, VALGRIND_CODSPEED_VERSION_STRING,
 };
@@ -11,22 +11,25 @@ use std::{env, path::Path, process::Command};
 use url::Url;
 
 fn get_codspeed_valgrind_filename(system_info: &SystemInfo) -> Result<String> {
-    let (version, architecture) = match (
-        system_info.os.as_str(),
-        system_info.os_version.as_str(),
-        system_info.arch.as_str(),
-    ) {
-        ("ubuntu", "22.04", "x86_64") | ("debian", "12", "x86_64") => ("22.04", "amd64"),
-        ("ubuntu", "24.04", "x86_64") => ("24.04", "amd64"),
-        ("ubuntu", "22.04", "aarch64") | ("debian", "12", "aarch64") => ("22.04", "arm64"),
-        ("ubuntu", "24.04", "aarch64") => ("24.04", "arm64"),
-        _ => bail!("Unsupported system"),
+    let Os::SupportedLinux { distro, version } = &system_info.os else {
+        bail!("Unsupported system");
     };
 
+    let (deb_ubuntu_version, architecture) =
+        match (distro, version.as_str(), system_info.arch.as_str()) {
+            (SupportedLinuxDistro::Ubuntu, "22.04", "x86_64")
+            | (SupportedLinuxDistro::Debian, "12", "x86_64") => ("22.04", "amd64"),
+            (SupportedLinuxDistro::Ubuntu, "24.04", "x86_64") => ("24.04", "amd64"),
+            (SupportedLinuxDistro::Ubuntu, "22.04", "aarch64")
+            | (SupportedLinuxDistro::Debian, "12", "aarch64") => ("22.04", "arm64"),
+            (SupportedLinuxDistro::Ubuntu, "24.04", "aarch64") => ("24.04", "arm64"),
+            _ => bail!("Unsupported system"),
+        };
+
     Ok(format!(
         "valgrind_{}_ubuntu-{}_{}.deb",
         VALGRIND_CODSPEED_DEB_VERSION.as_str(),
-        version,
+        deb_ubuntu_version,
         architecture
     ))
 }
@@ -175,8 +178,7 @@ mod tests {
     #[test]
     fn test_system_info_to_codspeed_valgrind_version_ubuntu() {
         let system_info = SystemInfo {
-            os: "ubuntu".to_string(),
-            os_version: "22.04".to_string(),
+            os: Os::from_id("ubuntu", "22.04"),
             arch: "x86_64".to_string(),
             ..SystemInfo::test()
         };
@@ -189,8 +191,7 @@ mod tests {
     #[test]
     fn test_system_info_to_codspeed_valgrind_version_ubuntu_24() {
         let system_info = SystemInfo {
-            os: "ubuntu".to_string(),
-            os_version: "24.04".to_string(),
+            os: Os::from_id("ubuntu", "24.04"),
             arch: "x86_64".to_string(),
             ..SystemInfo::test()
         };
@@ -203,8 +204,7 @@ mod tests {
     #[test]
     fn test_system_info_to_codspeed_valgrind_version_debian() {
         let system_info = SystemInfo {
-            os: "debian".to_string(),
-            os_version: "12".to_string(),
+            os: Os::from_id("debian", "12"),
             arch: "x86_64".to_string(),
             ..SystemInfo::test()
         };
@@ -217,8 +217,7 @@ mod tests {
     #[test]
     fn test_system_info_to_codspeed_valgrind_version_ubuntu_arm() {
         let system_info = SystemInfo {
-            os: "ubuntu".to_string(),
-            os_version: "22.04".to_string(),
+            os: Os::from_id("ubuntu", "22.04"),
             arch: "aarch64".to_string(),
             ..SystemInfo::test()
         };

src/executor/wall_time/executor.rs

@@ -10,11 +10,11 @@ use crate::executor::helpers::get_bench_command::get_bench_command;
 use crate::executor::helpers::run_command_with_log_pipe::run_command_with_log_pipe;
 use crate::executor::helpers::run_with_env::wrap_with_env;
 use crate::executor::helpers::run_with_sudo::wrap_with_sudo;
-use crate::executor::{ExecutionContext, ExecutorName};
+use crate::executor::{ExecutionContext, ExecutorName, ExecutorSupport};
 use crate::instruments::mongo_tracer::MongoTracer;
 use crate::prelude::*;
 use crate::runner_mode::RunnerMode;
-use crate::system::SystemInfo;
+use crate::system::{Os, SystemInfo};
 use async_trait::async_trait;
 use std::fs::canonicalize;
 use std::io::Write;
@@ -122,7 +122,23 @@ impl Executor for WallTimeExecutor {
     }
 
     fn tool_status(&self) -> ToolStatus {
-        super::perf::setup::get_perf_status()
+        if self.perf.is_some() {
+            super::perf::setup::get_perf_status()
+        } else {
+            // No profiler tool wired up on this OS yet — report as not installed.
+            ToolStatus {
+                tool_name: "perf".to_string(),
+                status: crate::executor::ToolInstallStatus::NotInstalled,
+            }
+        }
+    }
+
+    fn support_level(&self, os: &Os) -> ExecutorSupport {
+        match os {
+            Os::SupportedLinux { .. } | Os::MacOs { .. } => ExecutorSupport::FullySupported,
+            Os::OtherLinux { .. } => ExecutorSupport::RequiresManualSetup,
+            Os::Unsupported { .. } => ExecutorSupport::Unsupported,
+        }
     }
 
     async fn setup(&self, system_info: &SystemInfo, setup_cache_dir: Option<&Path>) -> Result<()> {