[ty] Add search paths info to unresolved import diagnostics (#20040)

Renkai · AlexWaygood · web-flow · commit 73720c73be98 · 2025-08-26T11:01:16.000-04:00
Fixes astral-sh/ty#457 --------- Co-authored-by: Alex Waygood <alex.waygood@gmail.com>
diff --git a/crates/ty/tests/cli/main.rs b/crates/ty/tests/cli/main.rs
@@ -263,6 +263,9 @@ fn cli_arguments_are_relative_to_the_current_directory() -> anyhow::Result<()> {
     3 |
     4 | stat = add(10, 15)
       |
+    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: make sure your Python environment is properly configured: https://docs.astral.sh/ty/modules/#python-environment
     info: rule `unresolved-import` is enabled by default
 
@@ -477,7 +480,7 @@ fn check_specific_paths() -> anyhow::Result<()> {
 
     assert_cmd_snapshot!(
         case.command(),
-        @r###"
+        @r"
     success: false
     exit_code: 1
     ----- stdout -----
@@ -489,6 +492,9 @@ fn check_specific_paths() -> anyhow::Result<()> {
     3 |
     4 | print(z)
       |
+    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: make sure your Python environment is properly configured: https://docs.astral.sh/ty/modules/#python-environment
     info: rule `unresolved-import` is enabled by default
 
@@ -498,14 +504,17 @@ fn check_specific_paths() -> anyhow::Result<()> {
     2 | import does_not_exist  # error: unresolved-import
       |        ^^^^^^^^^^^^^^
       |
+    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: make sure your Python environment is properly configured: https://docs.astral.sh/ty/modules/#python-environment
     info: rule `unresolved-import` is enabled by default
 
     Found 2 diagnostics
 
     ----- stderr -----
     WARN ty is pre-release software and not ready for production use. Expect to encounter bugs, missing features, and fatal errors.
-    "###
+    "
     );
 
     // Now check only the `tests` and `other.py` files.
@@ -524,6 +533,9 @@ fn check_specific_paths() -> anyhow::Result<()> {
     3 |
     4 | print(z)
       |
+    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: make sure your Python environment is properly configured: https://docs.astral.sh/ty/modules/#python-environment
     info: rule `unresolved-import` is enabled by default
 
@@ -533,6 +545,9 @@ fn check_specific_paths() -> anyhow::Result<()> {
     2 | import does_not_exist  # error: unresolved-import
       |        ^^^^^^^^^^^^^^
       |
+    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: make sure your Python environment is properly configured: https://docs.astral.sh/ty/modules/#python-environment
     info: rule `unresolved-import` is enabled by default
 
diff --git a/crates/ty/tests/cli/python_environment.rs b/crates/ty/tests/cli/python_environment.rs
@@ -333,6 +333,10 @@ import bar",
       |        ^^^
     2 | import bar
       |
+    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>/strange-venv-location/lib/python3.13/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
 
@@ -378,6 +382,11 @@ fn lib64_site_packages_directory_on_unix() -> anyhow::Result<()> {
     1 | import foo, bar, baz
       |                  ^^^
       |
+    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/lib/python3.13/site-packages (site-packages)
+    info:   4. <temp_dir>/.venv/lib64/python3.13/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
 
@@ -1273,6 +1282,9 @@ home = ./
     3 | from package1 import ChildConda
     4 | from package1 import WorkingVenv
       |
+    info: Searched in the following paths during module resolution:
+    info:   1. <temp_dir>/project (first-party code)
+    info:   2. vendored://stdlib (stdlib typeshed stubs vendored by ty)
     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
 
@@ -1285,6 +1297,9 @@ home = ./
     4 | from package1 import WorkingVenv
     5 | from package1 import BaseConda
       |
+    info: Searched in the following paths during module resolution:
+    info:   1. <temp_dir>/project (first-party code)
+    info:   2. vendored://stdlib (stdlib typeshed stubs vendored by ty)
     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
 
@@ -1297,6 +1312,9 @@ home = ./
       |      ^^^^^^^^
     5 | from package1 import BaseConda
       |
+    info: Searched in the following paths during module resolution:
+    info:   1. <temp_dir>/project (first-party code)
+    info:   2. vendored://stdlib (stdlib typeshed stubs vendored by ty)
     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
 
@@ -1308,6 +1326,9 @@ home = ./
     5 | from package1 import BaseConda
       |      ^^^^^^^^
       |
+    info: Searched in the following paths during module resolution:
+    info:   1. <temp_dir>/project (first-party code)
+    info:   2. vendored://stdlib (stdlib typeshed stubs vendored by ty)
     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
 
@@ -1716,6 +1737,10 @@ fn default_root_tests_package() -> anyhow::Result<()> {
     4 |
     5 | print(f"{foo} {bar}")
       |
+    info: Searched in the following paths during module resolution:
+    info:   1. <temp_dir>/ (first-party code)
+    info:   2. <temp_dir>/src (first-party code)
+    info:   3. vendored://stdlib (stdlib typeshed stubs vendored by ty)
     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
 
diff --git a/crates/ty/tests/cli/rule_selection.rs b/crates/ty/tests/cli/rule_selection.rs
@@ -89,7 +89,7 @@ fn cli_rule_severity() -> anyhow::Result<()> {
 
     // Assert that there's an `unresolved-reference` diagnostic (error)
     // and an unresolved-import (error) diagnostic by default.
-    assert_cmd_snapshot!(case.command(), @r###"
+    assert_cmd_snapshot!(case.command(), @r"
     success: false
     exit_code: 1
     ----- stdout -----
@@ -101,6 +101,9 @@ fn cli_rule_severity() -> anyhow::Result<()> {
     3 |
     4 | y = 4 / 0
       |
+    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: make sure your Python environment is properly configured: https://docs.astral.sh/ty/modules/#python-environment
     info: rule `unresolved-import` is enabled by default
 
@@ -118,7 +121,7 @@ fn cli_rule_severity() -> anyhow::Result<()> {
 
     ----- stderr -----
     WARN ty is pre-release software and not ready for production use. Expect to encounter bugs, missing features, and fatal errors.
-    "###);
+    ");
 
     assert_cmd_snapshot!(
         case
@@ -141,6 +144,9 @@ fn cli_rule_severity() -> anyhow::Result<()> {
     3 |
     4 | y = 4 / 0
       |
+    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: make sure your Python environment is properly configured: https://docs.astral.sh/ty/modules/#python-environment
     info: rule `unresolved-import` was selected on the command line
 
diff --git a/crates/ty_python_semantic/resources/mdtest/snapshots/basic.md_-_Structures_-_Multiple_objects_imp…_(cbfbf5ff94e6e104).snap b/crates/ty_python_semantic/resources/mdtest/snapshots/basic.md_-_Structures_-_Multiple_objects_imp…_(cbfbf5ff94e6e104).snap
@@ -26,6 +26,9 @@ error[unresolved-import]: Cannot resolve imported module `does_not_exist`
 2 | from does_not_exist import foo, bar, baz
   |      ^^^^^^^^^^^^^^
   |
+info: Searched in the following paths during module resolution:
+info:   1. /src (first-party code)
+info:   2. vendored://stdlib (stdlib typeshed stubs vendored by ty)
 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
 
diff --git a/crates/ty_python_semantic/resources/mdtest/snapshots/basic.md_-_Structures_-_Unresolvable_module_…_(846453deaca1071c).snap b/crates/ty_python_semantic/resources/mdtest/snapshots/basic.md_-_Structures_-_Unresolvable_module_…_(846453deaca1071c).snap
@@ -24,6 +24,9 @@ error[unresolved-import]: Cannot resolve imported module `zqzqzqzqzqzqzq`
 1 | import zqzqzqzqzqzqzq  # error: [unresolved-import] "Cannot resolve imported module `zqzqzqzqzqzqzq`"
   |        ^^^^^^^^^^^^^^
   |
+info: Searched in the following paths during module resolution:
+info:   1. /src (first-party code)
+info:   2. vendored://stdlib (stdlib typeshed stubs vendored by ty)
 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
 
diff --git a/crates/ty_python_semantic/resources/mdtest/snapshots/basic.md_-_Structures_-_Unresolvable_submodu…_(4fad4be9778578b7).snap b/crates/ty_python_semantic/resources/mdtest/snapshots/basic.md_-_Structures_-_Unresolvable_submodu…_(4fad4be9778578b7).snap
@@ -36,6 +36,9 @@ error[unresolved-import]: Cannot resolve imported module `a.foo`
 3 |
 4 | # Topmost component unresolvable:
   |
+info: Searched in the following paths during module resolution:
+info:   1. /src (first-party code)
+info:   2. vendored://stdlib (stdlib typeshed stubs vendored by ty)
 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
 
@@ -49,6 +52,9 @@ error[unresolved-import]: Cannot resolve imported module `b.foo`
 5 | import b.foo  # error: [unresolved-import] "Cannot resolve imported module `b.foo`"
   |        ^^^^^
   |
+info: Searched in the following paths during module resolution:
+info:   1. /src (first-party code)
+info:   2. vendored://stdlib (stdlib typeshed stubs vendored by ty)
 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
 
diff --git a/crates/ty_python_semantic/resources/mdtest/snapshots/unresolved_import.md_-_Unresolved_import_di…_-_An_unresolvable_impo…_(72d090df51ea97b8).snap b/crates/ty_python_semantic/resources/mdtest/snapshots/unresolved_import.md_-_Unresolved_import_di…_-_An_unresolvable_impo…_(72d090df51ea97b8).snap
@@ -28,6 +28,9 @@ error[unresolved-import]: Cannot resolve imported module `does_not_exist`
 2 |
 3 | x = does_not_exist.foo
   |
+info: Searched in the following paths during module resolution:
+info:   1. /src (first-party code)
+info:   2. vendored://stdlib (stdlib typeshed stubs vendored by ty)
 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
 
diff --git a/crates/ty_python_semantic/resources/mdtest/snapshots/unresolved_import.md_-_Unresolved_import_di…_-_Using_`from`_with_an…_(9fa713dfa17cc404).snap b/crates/ty_python_semantic/resources/mdtest/snapshots/unresolved_import.md_-_Unresolved_import_di…_-_Using_`from`_with_an…_(9fa713dfa17cc404).snap
@@ -28,6 +28,9 @@ error[unresolved-import]: Cannot resolve imported module `does_not_exist`
 2 |
 3 | stat = add(10, 15)
   |
+info: Searched in the following paths during module resolution:
+info:   1. /src (first-party code)
+info:   2. vendored://stdlib (stdlib typeshed stubs vendored by ty)
 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
 
diff --git a/crates/ty_python_semantic/src/module_resolver/mod.rs b/crates/ty_python_semantic/src/module_resolver/mod.rs
@@ -10,8 +10,7 @@ pub use resolver::{resolve_module, resolve_real_module};
 use ruff_db::system::SystemPath;
 
 use crate::Db;
-use crate::module_resolver::resolver::{ModuleResolveMode, search_paths};
-use resolver::SearchPathIterator;
+pub(crate) use resolver::{ModuleResolveMode, SearchPathIterator, search_paths};
 
 mod list;
 mod module;
diff --git a/crates/ty_python_semantic/src/module_resolver/path.rs b/crates/ty_python_semantic/src/module_resolver/path.rs
@@ -700,6 +700,25 @@ impl SearchPath {
             SearchPathInner::StandardLibraryVendored(_) => "std-vendored",
         }
     }
+
+    /// Returns a string suitable for describing what kind of search path this is
+    /// in user-facing diagnostics.
+    #[must_use]
+    pub(crate) fn describe_kind(&self) -> &'static str {
+        match *self.0 {
+            SearchPathInner::Extra(_) => {
+                "extra search path specified on the CLI or in your config file"
+            }
+            SearchPathInner::FirstParty(_) => "first-party code",
+            SearchPathInner::StandardLibraryCustom(_) => {
+                "custom stdlib stubs specified on the CLI or in your config file"
+            }
+            SearchPathInner::StandardLibraryReal(_) => "runtime stdlib source code",
+            SearchPathInner::SitePackages(_) => "site-packages",
+            SearchPathInner::Editable(_) => "editable install",
+            SearchPathInner::StandardLibraryVendored(_) => "stdlib typeshed stubs vendored by ty",
+        }
+    }
 }
 
 impl PartialEq<SystemPath> for SearchPath {
diff --git a/crates/ty_python_semantic/src/types/infer.rs b/crates/ty_python_semantic/src/types/infer.rs
@@ -64,7 +64,9 @@ use super::string_annotation::{
 use super::subclass_of::SubclassOfInner;
 use super::{ClassBase, add_inferred_python_version_hint_to_diagnostic};
 use crate::module_name::{ModuleName, ModuleNameResolutionError};
-use crate::module_resolver::{KnownModule, file_to_module, resolve_module};
+use crate::module_resolver::{
+    KnownModule, ModuleResolveMode, file_to_module, resolve_module, search_paths,
+};
 use crate::node_key::NodeKey;
 use crate::place::{
     Boundness, ConsideredDefinitions, LookupError, Place, PlaceAndQualifiers,
@@ -4983,6 +4985,26 @@ impl<'db, 'ast> TypeInferenceBuilder<'db, 'ast> {
                 }
             }
 
+            // Add search paths information to the diagnostic
+            // Use the same search paths function that is used in actual module resolution
+            let mut search_paths =
+                search_paths(self.db(), ModuleResolveMode::StubsAllowed).peekable();
+
+            if search_paths.peek().is_some() {
+                diagnostic.info(format_args!(
+                    "Searched in the following paths during module resolution:"
+                ));
+
+                for (index, path) in search_paths.enumerate() {
+                    diagnostic.info(format_args!(
+                        "  {}. {} ({})",
+                        index + 1,
+                        path,
+                        path.describe_kind()
+                    ));
+                }
+            }
+
             diagnostic.info(
                 "make sure your Python environment is properly configured: \
                 https://docs.astral.sh/ty/modules/#python-environment",

Original file line number	Diff line number	Diff line change
@@ -26,6 +26,9 @@ error[unresolved-import]: Cannot resolve imported module `does_not_exist`
`26`	`26`	`2 \| from does_not_exist import foo, bar, baz`
`27`	`27`	`\| ^^^^^^^^^^^^^^`
`28`	`28`	`\|`
	`29`	`+info: Searched in the following paths during module resolution:`
	`30`	`+info: 1. /src (first-party code)`
	`31`	`+info: 2. vendored://stdlib (stdlib typeshed stubs vendored by ty)`
`29`	`32`	`info: make sure your Python environment is properly configured: https://docs.astral.sh/ty/modules/#python-environment`
`30`	`33`	info: rule `unresolved-import` is enabled by default
`31`	`34`
Original file line number	Diff line number	Diff line change
@@ -24,6 +24,9 @@ error[unresolved-import]: Cannot resolve imported module `zqzqzqzqzqzqzq`
`24`	`24`	1 \| import zqzqzqzqzqzqzq # error: [unresolved-import] "Cannot resolve imported module `zqzqzqzqzqzqzq`"
`25`	`25`	`\| ^^^^^^^^^^^^^^`
`26`	`26`	`\|`
	`27`	`+info: Searched in the following paths during module resolution:`
	`28`	`+info: 1. /src (first-party code)`
	`29`	`+info: 2. vendored://stdlib (stdlib typeshed stubs vendored by ty)`
`27`	`30`	`info: make sure your Python environment is properly configured: https://docs.astral.sh/ty/modules/#python-environment`
`28`	`31`	info: rule `unresolved-import` is enabled by default
`29`	`32`
Original file line number	Diff line number	Diff line change
@@ -28,6 +28,9 @@ error[unresolved-import]: Cannot resolve imported module `does_not_exist`
`28`	`28`	`2 \|`
`29`	`29`	`3 \| x = does_not_exist.foo`
`30`	`30`	`\|`
	`31`	`+info: Searched in the following paths during module resolution:`
	`32`	`+info: 1. /src (first-party code)`
	`33`	`+info: 2. vendored://stdlib (stdlib typeshed stubs vendored by ty)`
`31`	`34`	`info: make sure your Python environment is properly configured: https://docs.astral.sh/ty/modules/#python-environment`
`32`	`35`	info: rule `unresolved-import` is enabled by default
`33`	`36`