[ty] Explain outdated uv versions in metadata errors

crates/ty_project/src/uv/command.rs

@@ -2,6 +2,7 @@
 
 use std::process::Output;
 
+use pep440_rs::Version;
 use ruff_db::system::{Command, CommandExecutor, System, SystemPath, WhichError};
 use ty_static::EnvVars;
 
@@ -31,11 +32,12 @@ impl Uv {
         let output = system
             .command_executor()
             .ok_or_else(unsupported_command_execution)
+            .map_err(UvMetadataError::Invocation)
             .and_then(|executor| self.execute(executor, target));
         Self::parse_metadata_output(system, output)
     }
 
-    /// Executes `uv workspace metadata` without interpreting its output.
+    /// Executes `uv workspace metadata`, checking for an unsupported uv version on failure.
     ///
     /// This operation only requires a detached command executor, so it can run on a background
     /// worker.
@@ -44,7 +46,7 @@ impl Uv {
         &self,
         executor: &dyn CommandExecutor,
         target: &MetadataTarget<'_>,
-    ) -> std::io::Result<Output> {
+    ) -> Result<Output, UvMetadataError> {
         let mut command = Command::new(self.executable.as_str());
         command.args(["workspace", "metadata", "--quiet"]);
 
@@ -79,15 +81,57 @@ impl Uv {
             start.elapsed().as_secs_f64()
         );
 
-        output
+        let output = output.map_err(UvMetadataError::Invocation)?;
+
+        // Before uv 0.12.3, `--quiet` suppresses the metadata JSON even on success.
+        // Only probe the version when metadata is unavailable, so successful calls stay cheap.
+        if (!output.status.success() || output.stdout.is_empty())
+            && let Some(version) = self.version(executor, target)
+            && version < Version::new([0, 12, 3])
+        {
+            return Err(UvMetadataError::UnsupportedVersion {
+                executable: self.executable.clone(),
+                version,
+            });
+        }
+
+        Ok(output)
+    }
+
+    fn version(
+        &self,
+        executor: &dyn CommandExecutor,
+        target: &MetadataTarget<'_>,
+    ) -> Option<Version> {
+        let mut command = Command::new(self.executable.as_str());
+        command.arg("--version");
+        let directory = match target {
+            MetadataTarget::Workspace(path) => Some(*path),
+            MetadataTarget::Script { path, .. } => path.parent(),
+        };
+        if let Some(directory) = directory {
+            command.current_dir(directory);
+        }
+        let output = executor.execute(command).ok()?;
+        if !output.status.success() {
+            return None;
+        }
+
+        std::str::from_utf8(&output.stdout)
+            .ok()?
+            .strip_prefix("uv ")?
+            .split_whitespace()
+            .next()?
+            .parse()
+            .ok()
     }
 
     /// Parses and validates the output returned by [`Self::execute`].
     pub(crate) fn parse_metadata_output(
         system: &dyn System,
-        output: std::io::Result<Output>,
+        output: Result<Output, UvMetadataError>,
     ) -> Result<UvMetadata, UvMetadataError> {
-        let output = output.map_err(UvMetadataError::Invocation)?;
+        let output = output?;
 
         if !output.status.success() {
             return Err(UvMetadataError::CommandFailed {

crates/ty_project/src/uv/environments.rs

@@ -81,8 +81,8 @@ use salsa::Setter;
 
 use crate::script::script_tag;
 use crate::uv::{
-    ScriptSyncRequest, ScriptSyncTask, Uv, UvMetadata, UvMetadataResult, UvMetadataService,
-    UvSyncTask,
+    ScriptSyncRequest, ScriptSyncTask, Uv, UvMetadata, UvMetadataError, UvMetadataResult,
+    UvMetadataService, UvSyncTask,
 };
 use crate::{Db, ProjectReloadResult, ProjectSyncProgressFactory, UseUv, UvSyncProgress};
 
@@ -710,7 +710,7 @@ fn apply_sync_result(
     db: &mut dyn Db,
     environment: ScriptEnvironment,
     request: &ScriptSyncRequest,
-    output: std::io::Result<std::process::Output>,
+    output: Result<std::process::Output, UvMetadataError>,
 ) {
     let (uv_metadata, initialization_error) = match Uv::parse_metadata_output(db.system(), output) {
         Ok(metadata) => (Some(metadata), None),

crates/ty_project/src/uv/metadata.rs

@@ -2,6 +2,7 @@ use std::collections::BTreeMap;
 use std::path::PathBuf;
 
 use char_str::CharStr;
+use pep440_rs::Version;
 use ruff_db::system::{System, SystemPath, SystemPathBuf};
 use serde::Deserialize;
 use thiserror::Error;
@@ -82,6 +83,12 @@ pub(crate) struct WorkspaceMember {
 
 #[derive(Debug, Error)]
 pub(crate) enum UvMetadataError {
+    #[error("uv {version} is too old; upgrade `{executable}` to uv 0.12.3 or newer")]
+    UnsupportedVersion {
+        executable: String,
+        version: Version,
+    },
+
     #[error("Failed to invoke `uv workspace metadata`: {0}")]
     Invocation(#[source] std::io::Error),
 

crates/ty_project/src/uv/service.rs

@@ -7,7 +7,7 @@ use ruff_db::files::File;
 use ruff_db::system::{CommandExecutor, System, SystemPathBuf};
 
 use super::command::unsupported_command_execution;
-use super::{MetadataTarget, ScriptEnvironmentCacheKey, Uv, uv_executable_error};
+use super::{MetadataTarget, ScriptEnvironmentCacheKey, Uv, UvMetadataError, uv_executable_error};
 use crate::UvSyncProgress;
 
 /// Runs workspace and standalone-script metadata requests with uv.
@@ -71,7 +71,7 @@ impl UvMetadataService {
             Err(error) => {
                 self.publish_result(UvMetadataResult {
                     task,
-                    output: Some(Err(error)),
+                    output: Some(Err(UvMetadataError::Invocation(error))),
                     progress,
                 });
                 return;
@@ -97,7 +97,7 @@ impl UvMetadataService {
             let job = error.into_inner();
             self.publish_result(UvMetadataResult {
                 task: job.task,
-                output: Some(Err(worker_disconnected())),
+                output: Some(Err(UvMetadataError::Invocation(worker_disconnected()))),
                 progress: job.progress,
             });
         }
@@ -211,7 +211,7 @@ impl UvSyncTask {
 pub(crate) struct UvMetadataResult {
     pub(crate) task: UvSyncTask,
     /// `None` if the worker skipped this request because it was cancelled before execution.
-    pub(crate) output: Option<std::io::Result<Output>>,
+    pub(crate) output: Option<Result<Output, UvMetadataError>>,
     pub(crate) progress: Option<Box<dyn UvSyncProgress>>,
 }