Hint at tool.uv.required-environments (#13575)

For the case where there was no matching wheel on sync, we previously
added a note about which wheels are available vs. on which platform you
are on. We extend this error message to link directly towards
`tool.uv.required-environments`, which otherwise has a discovery
problem.

On Linux (Setting `tool.uv.required-environments` doesn't help here
either, but it's a clear example):

```
[project]
name = "debug"
version = "0.1.0"
requires-python = "==3.10.*"
dependencies = ["tensorflow-macos>=2.13.1"]
```

```
Resolved 41 packages in 24ms
error: Distribution `tensorflow-macos==2.16.2 @ registry+https://pypi.org/simple` can't be installed because it doesn't have a source distribution or wheel for the current platform

hint: You're on Linux (`manylinux_2_39_x86_64`), but there are no wheels for the current platform, consider configuring `tool.uv.required-environments`.
hint: `tensorflow-macos` (v2.16.2) only has wheels for the following platform: `macosx_12_0_arm64`.
```


![image](https://github.com/user-attachments/assets/b6b49461-10d6-4e1d-bc0a-5d35d98e33d0)

---------

Co-authored-by: Zanie Blue <contact@zanie.dev>

crates/uv-resolver/src/lock/mod.rs

@@ -5084,32 +5084,23 @@ impl std::fmt::Display for WheelTagHint {
                     } else {
                         format!("`{}`", best.cyan())
                     };
-                    if let Some(version) = version {
+                    let package_ref = if let Some(version) = version {
-                        write!(
+                        format!("`{}` ({})", package.cyan(), format!("v{version}").cyan())
-                            f,
-                            "{}{} You're on {}, but `{}` ({}) only has wheels for the following platform{s}: {}",
-                            "hint".bold().cyan(),
-                            ":".bold(),
-                            best,
-                            package.cyan(),
-                            format!("v{version}").cyan(),
-                            tags.iter()
-                                .map(|tag| format!("`{}`", tag.cyan()))
-                                .join(", "),
-                        )
                     } else {
-                        write!(
+                        format!("`{}`", package.cyan())
-                            f,
+                    };
-                            "{}{} You're on {}, but `{}` only has wheels for the following platform{s}: {}",
+                    writeln!(
-                            "hint".bold().cyan(),
+                        f,
-                            ":".bold(),
+                        "{}{} You're on {}, but {} only has wheels for the following platform{s}: {}; consider adding your platform to `{}` to ensure uv resolves to a version with compatible wheels",
-                            best,
+                        "hint".bold().cyan(),
-                            package.cyan(),
+                        ":".bold(),
-                            tags.iter()
+                        best,
-                                .map(|tag| format!("`{}`", tag.cyan()))
+                        package_ref,
-                                .join(", "),
+                        tags.iter()
-                        )
+                            .map(|tag| format!("`{}`", tag.cyan()))
-                    }
+                            .join(", "),
+                        "tool.uv.required-environments".green()
+                    )
                 } else {
                     if let Some(version) = version {
                         write!(

crates/uv/tests/it/sync.rs

@@ -9608,3 +9608,71 @@ fn direct_url_dependency_metadata() -> Result<()> {
 
     Ok(())
 }
+
+#[cfg(unix)]
+#[test]
+fn sync_required_environment_hint() -> Result<()> {
+    let context = TestContext::new("3.13");
+
+    let pyproject_toml = context.temp_dir.child("pyproject.toml");
+    pyproject_toml.write_str(
+        r#"
+        [project]
+        name = "example"
+        version = "0.1.0"
+        requires-python = ">=3.13.2"
+        dependencies = ["wheel_tag_test"]
+        "#,
+    )?;
+
+    // Populate the `--find-links` entries.
+    fs_err::create_dir_all(context.temp_dir.join("links"))?;
+
+    for entry in fs_err::read_dir(context.workspace_root.join("scripts/links"))? {
+        let entry = entry?;
+        let path = entry.path();
+        if path
+            .file_name()
+            .and_then(|file_name| file_name.to_str())
+            .is_some_and(|file_name| file_name.starts_with("wheel_tag_test-"))
+        {
+            let dest = context
+                .temp_dir
+                .join("links")
+                .join(path.file_name().unwrap());
+            fs_err::copy(&path, &dest)?;
+        }
+    }
+
+    uv_snapshot!(context.filters(), context.lock()
+            .arg("--no-index")
+            .arg("--find-links")
+            .arg(context.temp_dir.join("links")), @r"
+    success: true
+    exit_code: 0
+    ----- stdout -----
+
+    ----- stderr -----
+    Resolved 2 packages in [TIME]
+    ");
+
+    let mut filters = context.filters();
+    filters.push((r"(macOS|Linux) \(`.*`\)", "[PLATFORM] (`[TAG]`)"));
+
+    uv_snapshot!(filters, context.sync()
+            .arg("--no-index")
+            .arg("--find-links")
+            .arg(context.temp_dir.join("links")), @r"
+    success: false
+    exit_code: 2
+    ----- stdout -----
+
+    ----- stderr -----
+    Resolved 2 packages in [TIME]
+    error: Distribution `wheel-tag-test==0.1.0 @ registry+links` can't be installed because it doesn't have a source distribution or wheel for the current platform
+
+    hint: You're on [PLATFORM] (`[TAG]`), but `wheel-tag-test` (v0.1.0) only has wheels for the following platform: `win_amd64`; consider adding your platform to `tool.uv.required-environments` to ensure uv resolves to a version with compatible wheels
+    ");
+
+    Ok(())
+}