Provide resolution hints in case of possible local name conflicts (#7505)

This enhances the hints generator in the resolver with some heuristic to
detect and warn in case of failures due to version mismatches on a local
package. Those may be the symptom of name conflict/shadowing with a
transitive dependency.

Closes: https://github.com/astral-sh/uv/issues/7329

---------

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

crates/uv-resolver/src/error.rs

@@ -258,6 +258,7 @@ impl std::fmt::Display for NoSolutionError {
             &self.incomplete_packages,
             &self.fork_urls,
             &self.markers,
+            &self.workspace_members,
             &mut additional_hints,
         );
         for hint in additional_hints {

crates/uv-resolver/src/pubgrub/report.rs

@@ -508,6 +508,7 @@ impl PubGrubReportFormatter<'_> {
         incomplete_packages: &FxHashMap<PackageName, BTreeMap<Version, IncompletePackage>>,
         fork_urls: &ForkUrls,
         markers: &ResolverMarkers,
+        workspace_members: &BTreeSet<PackageName>,
         output_hints: &mut IndexSet<PubGrubHint>,
     ) {
         match derivation_tree {
@@ -526,9 +527,7 @@ impl PubGrubReportFormatter<'_> {
                             output_hints,
                         );
                     }
-                }
 
-                if let PubGrubPackageInner::Package { name, .. } = &**package {
                     // Check for no versions due to no `--find-links` flat index
                     Self::index_hints(
                         package,
@@ -547,6 +546,22 @@ impl PubGrubReportFormatter<'_> {
                 dependency,
                 dependency_set,
             )) => {
+                // Check for a dependency on a workspace package by a non-workspace package.
+                // Generally, this indicates that the workspace package is shadowing a transitive
+                // dependency name.
+                if let (Some(package_name), Some(dependency_name)) =
+                    (package.name(), dependency.name())
+                {
+                    if workspace_members.contains(dependency_name)
+                        && !workspace_members.contains(package_name)
+                    {
+                        output_hints.insert(PubGrubHint::DependsOnWorkspacePackage {
+                            package: package.clone(),
+                            dependency: dependency.clone(),
+                            workspace: self.is_workspace() && !self.is_single_project_workspace(),
+                        });
+                    }
+                }
                 // Check for no versions due to `Requires-Python`.
                 if matches!(
                     &**dependency,
@@ -571,6 +586,7 @@ impl PubGrubReportFormatter<'_> {
                     incomplete_packages,
                     fork_urls,
                     markers,
+                    workspace_members,
                     output_hints,
                 );
                 self.generate_hints(
@@ -581,6 +597,7 @@ impl PubGrubReportFormatter<'_> {
                     incomplete_packages,
                     fork_urls,
                     markers,
+                    workspace_members,
                     output_hints,
                 );
             }
@@ -802,6 +819,11 @@ pub(crate) enum PubGrubHint {
         // excluded from `PartialEq` and `Hash`
         package_requires_python: Range<Version>,
     },
+    DependsOnWorkspacePackage {
+        package: PubGrubPackage,
+        dependency: PubGrubPackage,
+        workspace: bool,
+    },
 }
 
 /// This private enum mirrors [`PubGrubHint`] but only includes fields that should be
@@ -842,6 +864,11 @@ enum PubGrubHintCore {
         source: PythonRequirementSource,
         requires_python: RequiresPython,
     },
+    DependsOnWorkspacePackage {
+        package: PubGrubPackage,
+        dependency: PubGrubPackage,
+        workspace: bool,
+    },
 }
 
 impl From<PubGrubHint> for PubGrubHintCore {
@@ -885,6 +912,15 @@ impl From<PubGrubHint> for PubGrubHintCore {
                 source,
                 requires_python,
             },
+            PubGrubHint::DependsOnWorkspacePackage {
+                package,
+                dependency,
+                workspace,
+            } => Self::DependsOnWorkspacePackage {
+                package,
+                dependency,
+                workspace,
+            },
         }
     }
 }
@@ -1080,6 +1116,30 @@ impl std::fmt::Display for PubGrubHint {
                     package_requires_python.bold(),
                 )
             }
+            Self::DependsOnWorkspacePackage {
+                package,
+                dependency,
+                workspace,
+            } => {
+                let your_project = if *workspace {
+                    "one of your workspace members"
+                } else {
+                    "your project"
+                };
+                let the_project = if *workspace {
+                    "the workspace member"
+                } else {
+                    "the project"
+                };
+                write!(
+                    f,
+                    "{}{} The package `{}` depends on the package `{}` but the name is shadowed by {your_project}. Consider changing the name of {the_project}.",
+                    "hint".bold().cyan(),
+                    ":".bold(),
+                    package,
+                    dependency,
+                )
+            }
         }
     }
 }