Allow user to constrain supported lock environments (#6210)

## Summary

The strategy here is: if the user provides supported environments, we
use those as the initial forks when resolving. As a result, we never add
or explore branches that are disjoint with the supported environments.
(If the supported environments change, we ignore the lockfile entirely,
so we don't have to worry about any interactions between supported
environments and the preference forks.)

Closes #6184.

STYLE.md

@@ -86,7 +86,7 @@ The documentation is divided into:
 1. When using `console` syntax, use `$` to indicate commands — everything else is output.
 1. Never use the `bash` syntax when displaying command output.
 1. Prefer `console` with `$` prefixed commands over `bash`.
-1. Command output should rarely be included — it's hard to keep up to date.
+1. Command output should rarely be included — it's hard to keep up-to-date.
 1. Use `title` for example files, e.g., `pyproject.toml`, `Dockerfile`, or `example.py`.
 
 ## CLI

crates/uv-client/src/httpcache/mod.rs

@@ -51,7 +51,7 @@ called a re-validation request.
 
 A re-validation request includes with it some metadata (usually an "entity tag"
 or `etag` for short) that was on the cached response (which is now stale).
-When we send this request, the server can compare it with its most up to date
+When we send this request, the server can compare it with its most up-to-date
 version of the resource. If its entity tag matches the one we gave it (among
 other possible criteria), then the server can skip returning the body and
 instead just return a small HTTP 304 NOT MODIFIED response. When we get this

crates/uv-git/src/git.rs

@@ -626,9 +626,9 @@ enum FastPathRev {
     /// date with what this rev resolves to on GitHub's server.
     UpToDate,
     /// The following SHA must be fetched in order for the local rev to become
-    /// up to date.
+    /// up-to-date.
     NeedsFetch(GitOid),
-    /// Don't know whether local rev is up to date. We'll fetch _all_ branches
+    /// Don't know whether local rev is up-to-date. We'll fetch _all_ branches
     /// and tags from the server and see what happens.
     Indeterminate,
 }

crates/uv-resolver/src/lock.rs

@@ -47,6 +47,8 @@ pub struct Lock {
     /// If this lockfile was built from a forking resolution with non-identical forks, store the
     /// forks in the lockfile so we can recreate them in subsequent resolutions.
     fork_markers: Vec<MarkerTree>,
+    /// The list of supported environments specified by the user.
+    supported_environments: Vec<MarkerTree>,
     /// The range of supported Python versions.
     requires_python: Option<RequiresPython>,
     /// We discard the lockfile if these options don't match.
@@ -161,6 +163,7 @@ impl Lock {
             requires_python,
             options,
             ResolverManifest::default(),
+            vec![],
             graph.fork_markers.clone(),
         )?;
         Ok(lock)
@@ -173,6 +176,7 @@ impl Lock {
         requires_python: Option<RequiresPython>,
         options: ResolverOptions,
         manifest: ResolverManifest,
+        supported_environments: Vec<MarkerTree>,
         fork_markers: Vec<MarkerTree>,
     ) -> Result<Self, LockError> {
         // Put all dependencies for each package in a canonical order and
@@ -329,6 +333,7 @@ impl Lock {
         Ok(Self {
             version,
             fork_markers,
+            supported_environments,
             requires_python,
             options,
             packages,
@@ -344,6 +349,13 @@ impl Lock {
         self
     }
 
+    /// Record the supported environments that were used to generate this lock.
+    #[must_use]
+    pub fn with_supported_environments(mut self, supported_environments: Vec<MarkerTree>) -> Self {
+        self.supported_environments = supported_environments;
+        self
+    }
+
     /// Returns the number of packages in the lockfile.
     pub fn len(&self) -> usize {
         self.packages.len()
@@ -384,6 +396,11 @@ impl Lock {
         self.options.exclude_newer
     }
 
+    /// Returns the supported environments that were used to generate this lock.
+    pub fn supported_environments(&self) -> &[MarkerTree] {
+        &self.supported_environments
+    }
+
     /// If this lockfile was built from a forking resolution with non-identical forks, return the
     /// markers of those forks, otherwise `None`.
     pub fn fork_markers(&self) -> &[MarkerTree] {
@@ -486,6 +503,7 @@ impl Lock {
         if let Some(ref requires_python) = self.requires_python {
             doc.insert("requires-python", value(requires_python.to_string()));
         }
+
         if !self.fork_markers.is_empty() {
             let fork_markers = each_element_on_its_line_array(
                 self.fork_markers
@@ -496,6 +514,16 @@ impl Lock {
             doc.insert("resolution-markers", value(fork_markers));
         }
 
+        if !self.supported_environments.is_empty() {
+            let supported_environments = each_element_on_its_line_array(
+                self.supported_environments
+                    .iter()
+                    .filter_map(MarkerTree::contents)
+                    .map(|marker| marker.to_string()),
+            );
+            doc.insert("supported-markers", value(supported_environments));
+        }
+
         // Write the settings that were used to generate the resolution.
         // This enables us to invalidate the lockfile if the user changes
         // their settings.
@@ -951,6 +979,8 @@ struct LockWire {
     /// forks in the lockfile so we can recreate them in subsequent resolutions.
     #[serde(rename = "resolution-markers", default)]
     fork_markers: Vec<MarkerTree>,
+    #[serde(rename = "supported-markers", default)]
+    supported_environments: Vec<MarkerTree>,
     /// We discard the lockfile if these options match.
     #[serde(default)]
     options: ResolverOptions,
@@ -966,6 +996,7 @@ impl From<Lock> for LockWire {
             version: lock.version,
             requires_python: lock.requires_python,
             fork_markers: lock.fork_markers,
+            supported_environments: lock.supported_environments,
             options: lock.options,
             manifest: lock.manifest,
             packages: lock.packages.into_iter().map(PackageWire::from).collect(),
@@ -1005,6 +1036,7 @@ impl TryFrom<LockWire> for Lock {
             wire.requires_python,
             wire.options,
             wire.manifest,
+            wire.supported_environments,
             wire.fork_markers,
         )
     }

crates/uv-resolver/src/resolution/graph.rs

@@ -174,7 +174,18 @@ impl ResolutionGraph {
                     vec![]
                 }
                 ResolverMarkers::Fork(_) => {
-                    panic!("A single fork must be universal");
+                    resolutions
+                        .iter()
+                        .map(|resolution| {
+                            resolution
+                                .markers
+                                .fork_markers()
+                                .expect("A non-forking resolution exists in forking mode")
+                                .clone()
+                        })
+                        // Any unsatisfiable forks were skipped.
+                        .filter(|fork| !fork.is_false())
+                        .collect()
                 }
             }
         } else {

crates/uv-resolver/src/snapshots/uv_resolver__lock__tests__hash_optional_missing.snap

@@ -6,6 +6,7 @@ Ok(
     Lock {
         version: 1,
         fork_markers: [],
+        supported_environments: [],
         requires_python: None,
         options: ResolverOptions {
             resolution_mode: Highest,

crates/uv-resolver/src/snapshots/uv_resolver__lock__tests__hash_optional_present.snap

@@ -6,6 +6,7 @@ Ok(
     Lock {
         version: 1,
         fork_markers: [],
+        supported_environments: [],
         requires_python: None,
         options: ResolverOptions {
             resolution_mode: Highest,

crates/uv-resolver/src/snapshots/uv_resolver__lock__tests__hash_required_present.snap

@@ -6,6 +6,7 @@ Ok(
     Lock {
         version: 1,
         fork_markers: [],
+        supported_environments: [],
         requires_python: None,
         options: ResolverOptions {
             resolution_mode: Highest,

crates/uv-resolver/src/snapshots/uv_resolver__lock__tests__missing_dependency_source_unambiguous.snap

@@ -6,6 +6,7 @@ Ok(
     Lock {
         version: 1,
         fork_markers: [],
+        supported_environments: [],
         requires_python: None,
         options: ResolverOptions {
             resolution_mode: Highest,

crates/uv-resolver/src/snapshots/uv_resolver__lock__tests__missing_dependency_source_version_unambiguous.snap

@@ -6,6 +6,7 @@ Ok(
     Lock {
         version: 1,
         fork_markers: [],
+        supported_environments: [],
         requires_python: None,
         options: ResolverOptions {
             resolution_mode: Highest,

crates/uv-resolver/src/snapshots/uv_resolver__lock__tests__missing_dependency_version_unambiguous.snap

@@ -6,6 +6,7 @@ Ok(
     Lock {
         version: 1,
         fork_markers: [],
+        supported_environments: [],
         requires_python: None,
         options: ResolverOptions {
             resolution_mode: Highest,

crates/uv-resolver/src/snapshots/uv_resolver__lock__tests__source_direct_has_subdir.snap

@@ -6,6 +6,7 @@ Ok(
     Lock {
         version: 1,
         fork_markers: [],
+        supported_environments: [],
         requires_python: None,
         options: ResolverOptions {
             resolution_mode: Highest,

crates/uv-resolver/src/snapshots/uv_resolver__lock__tests__source_direct_no_subdir.snap

@@ -6,6 +6,7 @@ Ok(
     Lock {
         version: 1,
         fork_markers: [],
+        supported_environments: [],
         requires_python: None,
         options: ResolverOptions {
             resolution_mode: Highest,

crates/uv-resolver/src/snapshots/uv_resolver__lock__tests__source_directory.snap

@@ -6,6 +6,7 @@ Ok(
     Lock {
         version: 1,
         fork_markers: [],
+        supported_environments: [],
         requires_python: None,
         options: ResolverOptions {
             resolution_mode: Highest,

crates/uv-resolver/src/snapshots/uv_resolver__lock__tests__source_editable.snap

@@ -6,6 +6,7 @@ Ok(
     Lock {
         version: 1,
         fork_markers: [],
+        supported_environments: [],
         requires_python: None,
         options: ResolverOptions {
             resolution_mode: Highest,

crates/uv-settings/src/settings.rs

@@ -64,6 +64,10 @@ pub struct Options {
     #[cfg_attr(feature = "schemars", schemars(skip))]
     dev_dependencies: serde::de::IgnoredAny,
 
+    #[serde(default, skip_serializing)]
+    #[cfg_attr(feature = "schemars", schemars(skip))]
+    environments: serde::de::IgnoredAny,
+
     #[serde(default, skip_serializing)]
     #[cfg_attr(feature = "schemars", schemars(skip))]
     managed: serde::de::IgnoredAny,

crates/uv-workspace/src/environments.rs

@@ -0,0 +1,78 @@
+use std::str::FromStr;
+
+use serde::ser::SerializeSeq;
+
+use pep508_rs::MarkerTree;
+
+#[derive(Debug, Default, Clone, Eq, PartialEq)]
+pub struct SupportedEnvironments(Vec<MarkerTree>);
+
+impl SupportedEnvironments {
+    /// Return the list of marker trees.
+    pub fn as_markers(&self) -> &[MarkerTree] {
+        &self.0
+    }
+
+    /// Convert the [`SupportedEnvironments`] struct into a list of marker trees.
+    pub fn into_markers(self) -> Vec<MarkerTree> {
+        self.0
+    }
+}
+
+/// Serialize a [`SupportedEnvironments`] struct into a list of marker strings.
+impl serde::Serialize for SupportedEnvironments {
+    fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
+    where
+        S: serde::Serializer,
+    {
+        let mut seq = serializer.serialize_seq(Some(self.0.len()))?;
+        for element in &self.0 {
+            if let Some(contents) = element.contents() {
+                seq.serialize_element(&contents)?;
+            }
+        }
+        seq.end()
+    }
+}
+
+/// Deserialize a marker string or list of marker strings into a [`SupportedEnvironments`] struct.
+impl<'de> serde::Deserialize<'de> for SupportedEnvironments {
+    fn deserialize<D>(deserializer: D) -> Result<SupportedEnvironments, D::Error>
+    where
+        D: serde::Deserializer<'de>,
+    {
+        struct StringOrVecVisitor;
+
+        impl<'de> serde::de::Visitor<'de> for StringOrVecVisitor {
+            type Value = SupportedEnvironments;
+
+            fn expecting(&self, formatter: &mut std::fmt::Formatter) -> std::fmt::Result {
+                formatter.write_str("a string or a list of strings")
+            }
+
+            fn visit_str<E>(self, value: &str) -> Result<Self::Value, E>
+            where
+                E: serde::de::Error,
+            {
+                let marker = MarkerTree::from_str(value).map_err(serde::de::Error::custom)?;
+                Ok(SupportedEnvironments(vec![marker]))
+            }
+
+            fn visit_seq<A>(self, mut seq: A) -> Result<Self::Value, A::Error>
+            where
+                A: serde::de::SeqAccess<'de>,
+            {
+                let mut markers = Vec::new();
+
+                while let Some(elem) = seq.next_element::<String>()? {
+                    let marker = MarkerTree::from_str(&elem).map_err(serde::de::Error::custom)?;
+                    markers.push(marker);
+                }
+
+                Ok(SupportedEnvironments(markers))
+            }
+        }
+
+        deserializer.deserialize_any(StringOrVecVisitor)
+    }
+}

crates/uv-workspace/src/lib.rs

@@ -1,8 +1,10 @@
+pub use environments::SupportedEnvironments;
 pub use workspace::{
     check_nested_workspaces, DiscoveryOptions, ProjectWorkspace, VirtualProject, Workspace,
     WorkspaceError, WorkspaceMember,
 };
 
+mod environments;
 pub mod pyproject;
 pub mod pyproject_mut;
 mod workspace;

crates/uv-workspace/src/pyproject.rs

@@ -14,6 +14,7 @@ use serde::{Deserialize, Serialize};
 use thiserror::Error;
 use url::Url;
 
+use crate::environments::SupportedEnvironments;
 use pep440_rs::VersionSpecifiers;
 use pypi_types::{RequirementSource, VerbatimParsedUrl};
 use uv_git::GitReference;
@@ -98,19 +99,49 @@ pub struct ToolUv {
         "#
     )]
     pub managed: Option<bool>,
+    /// The project's development dependencies. Development dependencies will be installed by
+    /// default in `uv run` and `uv sync`, but will not appear in the project's published metadata.
     #[cfg_attr(
         feature = "schemars",
         schemars(
             with = "Option<Vec<String>>",
             description = "PEP 508-style requirements, e.g., `ruff==0.5.0`, or `ruff @ https://...`."
         )
     )]
+    #[option(
+        default = r#"[]"#,
+        value_type = "list[str]",
+        example = r#"
+            dev_dependencies = ["ruff==0.5.0"]
+        "#
+    )]
     pub dev_dependencies: Option<Vec<pep508_rs::Requirement<VerbatimParsedUrl>>>,
+    /// A list of supported environments against which to resolve dependencies.
+    ///
+    /// By default, uv will resolve for all possible environments during a `uv lock` operation.
+    /// However, you can restrict the set of supported environments to improve performance and avoid
+    /// unsatisfiable branches in the solution space.
+    #[cfg_attr(
+        feature = "schemars",
+        schemars(
+            with = "Option<Vec<String>>",
+            description = "A list of environment markers, e.g. `python_version >= '3.6'`."
+        )
+    )]
+    #[option(
+        default = r#"[]"#,
+        value_type = "str | list[str]",
+        example = r#"
+            # Resolve for macOS, but not for Linux or Windows.
+            environments = ["sys_platform == 'darwin'"]
+        "#
+    )]
+    pub environments: Option<SupportedEnvironments>,
     #[cfg_attr(
         feature = "schemars",
         schemars(
             with = "Option<Vec<String>>",
-            description = "PEP 508 style requirements, e.g. `ruff==0.5.0`, or `ruff @ https://...`."
+            description = "PEP 508-style requirements, e.g. `ruff==0.5.0`, or `ruff @ https://...`."
         )
     )]
     pub override_dependencies: Option<Vec<pep508_rs::Requirement<VerbatimParsedUrl>>>,