[ty] Allow discovering dependencies in system Python environments (#22994)

## Summary

Fixes astral-sh/ty#2068.

This change allows ty to discover and use dependencies installed in
system Python environments where ty itself is installed.

The subtlety here is in the case where we discover a local `.venv` AND
ty is installed in a different Python env. In this case, we prioritize
the local `.venv`, to avoid false-negatives due to accidental reliance
on globally installed packages.

## Test Plan

Added test; existing tests continue to pass.

Co-authored-by: Claude <noreply@anthropic.com>

Author: carljm

crates/ty/tests/cli/python_environment.rs

@@ -2181,7 +2181,7 @@ fn ty_environment_and_active_environment() -> anyhow::Result<()> {
 }
 
 /// When ty is installed in a system environment rather than a virtual environment, it should
-/// not include the environment's site-packages in its search path.
+/// include the environment's site-packages in its search path.
 #[test]
 fn ty_environment_is_system_not_virtual() -> anyhow::Result<()> {
     let ty_system_site_packages = if cfg!(windows) {
@@ -2199,7 +2199,7 @@ fn ty_environment_is_system_not_virtual() -> anyhow::Result<()> {
     let ty_package_path = format!("{ty_system_site_packages}/system_package/__init__.py");
 
     let case = CliTest::with_files([
-        // Package in system Python installation (should NOT be discovered)
+        // Package in system Python installation (should be discovered)
         (ty_package_path.as_str(), "class SystemClass: ..."),
         // Note: NO pyvenv.cfg - this is a system installation, not a venv
         (
@@ -2212,18 +2212,85 @@ fn ty_environment_is_system_not_virtual() -> anyhow::Result<()> {
     .with_ty_at(ty_executable_path)?;
 
     assert_cmd_snapshot!(case.command(), @"
+    success: true
+    exit_code: 0
+    ----- stdout -----
+    All checks passed!
+
+    ----- stderr -----
+    ");
+
+    Ok(())
+}
+
+/// When ty is installed in a system environment and there's also a local `.venv`,
+/// the system environment's site-packages should not be included at all.
+/// This is the opposite of when ty is installed in a virtual environment (like `uvx --with ...`),
+/// where ty's venv takes priority but both are included.
+#[test]
+fn ty_system_environment_and_local_venv() -> anyhow::Result<()> {
+    let ty_system_site_packages = if cfg!(windows) {
+        "system-python/Lib/site-packages"
+    } else {
+        "system-python/lib/python3.13/site-packages"
+    };
+
+    let ty_executable_path = if cfg!(windows) {
+        "system-python/Scripts/ty.exe"
+    } else {
+        "system-python/bin/ty"
+    };
+
+    let local_venv_site_packages = if cfg!(windows) {
+        ".venv/Lib/site-packages"
+    } else {
+        ".venv/lib/python3.13/site-packages"
+    };
+
+    let ty_unique_package = format!("{ty_system_site_packages}/system_package/__init__.py");
+    let local_unique_package = format!("{local_venv_site_packages}/local_package/__init__.py");
+
+    let case = CliTest::with_files([
+        (ty_unique_package.as_str(), "class SystemEnvClass: ..."),
+        (local_unique_package.as_str(), "class LocalClass: ..."),
+        // Note: NO pyvenv.cfg for system-python - this is a system installation, not a venv
+        (
+            ".venv/pyvenv.cfg",
+            r"
+            home = ./
+            version = 3.13
+            ",
+        ),
+        (
+            "test.py",
+            r"
+            # Should NOT resolve (system Python site-packages excluded when .venv exists)
+            from system_package import SystemEnvClass
+            # Should resolve from local .venv
+            from local_package import LocalClass
+            ",
+        ),
+    ])?
+    .with_ty_at(ty_executable_path)?
+    .with_filter(&site_packages_filter("3.13"), "<site-packages>");
+
+    assert_cmd_snapshot!(case.command().env_remove("VIRTUAL_ENV"), @"
     success: false
     exit_code: 1
     ----- stdout -----
     error[unresolved-import]: Cannot resolve imported module `system_package`
-     --> test.py:2:6
+     --> test.py:3:6
       |
-    2 | from system_package import SystemClass
+    2 | # Should NOT resolve (system Python site-packages excluded when .venv exists)
+    3 | from system_package import SystemEnvClass
       |      ^^^^^^^^^^^^^^
+    4 | # Should resolve from local .venv
+    5 | from local_package import LocalClass
       |
     info: Searched in the following paths during module resolution:
     info:   1. <temp_dir>/ (first-party code)
     info:   2. vendored://stdlib (stdlib typeshed stubs vendored by ty)
+    info:   3. <temp_dir>/.venv/<site-packages> (site-packages)
     info: make sure your Python environment is properly configured: https://docs.astral.sh/ty/modules/#python-environment
     info: rule `unresolved-import` is enabled by default
 

crates/ty_project/src/metadata/options.rs

@@ -184,14 +184,13 @@ impl Options {
             }
         };
 
-        let self_site_packages = self_environment_search_paths(
+        let self_environment = self_environment_search_paths(
             python_environment
                 .as_ref()
                 .map(ty_python_semantic::PythonEnvironment::origin)
                 .cloned(),
             system,
-        )
-        .unwrap_or_default();
+        );
 
         let site_packages_paths = if let Some(python_environment) = python_environment.as_ref() {
             let site_packages_paths = python_environment
@@ -210,10 +209,19 @@ impl Options {
                     }
                 }
             };
-            self_site_packages.concatenate(site_packages_paths)
+            match self_environment {
+                // When ty is installed in a virtual environment (e.g., `uvx --with ...`),
+                // the self-environment takes priority over the discovered environment.
+                Some((self_site_packages, true)) => {
+                    self_site_packages.concatenate(site_packages_paths)
+                }
+                // When ty is installed in a system Python, do not include the system
+                // Python's site-packages if there's a discovered project environment.
+                Some((_, false)) | None => site_packages_paths,
+            }
         } else {
             tracing::debug!("No virtual environment found");
-            self_site_packages
+            self_environment.map(|(paths, _)| paths).unwrap_or_default()
         };
 
         let real_stdlib_path = python_environment.as_ref().and_then(|python_environment| {
@@ -518,10 +526,15 @@ impl Options {
 ///
 /// Since ty may be executed from an arbitrary non-Python location, errors during discovery of ty's
 /// environment are not raised, instead [`None`] is returned.
+///
+/// Returns a tuple of (`site_packages`, `is_virtual_env`). When the self-environment is a virtual
+/// environment (e.g., `uvx --with ...`), it takes priority over other environments.
+/// When it's a system Python and there's a project environment (like `.venv`), the system
+/// Python's site-packages are excluded entirely.
 fn self_environment_search_paths(
     existing_origin: Option<SysPrefixPathOrigin>,
     system: &dyn System,
-) -> Option<SitePackagesPaths> {
+) -> Option<(SitePackagesPaths, bool)> {
     if existing_origin.is_some_and(|origin| !origin.allows_concatenation_with_self_environment()) {
         return None;
     }
@@ -535,15 +548,17 @@ fn self_environment_search_paths(
         .inspect_err(|err| tracing::debug!("Failed to discover ty's environment: {err}"))
         .ok()?;
 
+    let is_virtual_env = environment.is_virtual();
+
     let search_paths = environment
         .site_packages_paths(system)
         .inspect_err(|err| {
             tracing::debug!("Failed to discover site-packages in ty's environment: {err}");
         })
-        .ok();
+        .ok()?;
 
     tracing::debug!("Using site-packages from ty's environment");
-    search_paths
+    Some((search_paths, is_virtual_env))
 }
 
 #[derive(

crates/ty_site_packages/src/lib.rs

@@ -276,6 +276,11 @@ impl PythonEnvironment {
             Self::System(env) => &env.root_path.origin,
         }
     }
+
+    /// Returns `true` if this is a virtual environment (has a `pyvenv.cfg` file).
+    pub fn is_virtual(&self) -> bool {
+        matches!(self, Self::Virtual(_))
+    }
 }
 
 /// Enumeration of the subdirectories of `sys.prefix` that could contain a
@@ -1709,14 +1714,8 @@ impl SysPrefixPathOrigin {
             | Self::Editor
             | Self::DerivedFromPyvenvCfg
             | Self::CondaPrefixVar
-            | Self::PythonBinary => false,
-            // It's not strictly true that the self environment must be virtual, e.g., ty could be
-            // installed in a system Python environment and users may expect us to respect
-            // dependencies installed alongside it. However, we're intentionally excluding support
-            // for this to start. Note a change here has downstream implications, i.e., we probably
-            // don't want the packages in a system environment to take precedence over those in a
-            // virtual environment and would need to reverse the ordering in that case.
-            Self::SelfEnvironment => true,
+            | Self::PythonBinary
+            | Self::SelfEnvironment => false,
         }
     }
 
@@ -2189,6 +2188,20 @@ mod tests {
         );
     }
 
+    #[test]
+    fn can_find_site_packages_directory_no_virtual_env_at_origin_self_environment() {
+        // Test that ty can discover dependencies in a system Python environment
+        // that it's installed into (issue #2068).
+        let test = PythonEnvironmentTestCase {
+            system: TestSystem::default(),
+            minor_version: 13,
+            free_threaded: false,
+            origin: SysPrefixPathOrigin::SelfEnvironment,
+            virtual_env: None,
+        };
+        test.run();
+    }
+
     #[test]
     fn can_find_site_packages_directory_venv_style_version_field_in_pyvenv_cfg() {
         // Shouldn't be converted to an mdtest because we want to assert