refactor(resolver): rename and document resolve_from_provider semantics

Rename resolve_from_provider() to find_all_matching_from_provider() to
better reflect its changed semantics after the resolver refactoring.

Key behavioral changes:
- Collects ALL matching candidates instead of single best one
- Bypasses resolvelib's full dependency resolver
- Passes empty incompatibilities={} dict (no version exclusion)
- Only safe because BaseProvider.get_dependencies() returns []

Added comprehensive documentation explaining:
- Why empty incompatibilities is safe (no transitive deps)
- That this bypasses resolvelib's backtracking logic
- Warning that extending get_dependencies() requires revisiting this

This addresses the concern that the empty incompatibilities dict could
silently produce incorrect results if dependency resolution logic changes.

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
Signed-off-by: Rohan Devasthale <rdevasth@redhat.com>

Author: rd4398

src/fromager/bootstrap_requirement_resolver.py

@@ -175,7 +175,7 @@ def _resolve(
                         req_type=req_type,
                         ignore_platform=False,
                     )
-                    results = resolver.resolve_from_provider(provider, req)
+                    results = resolver.find_all_matching_from_provider(provider, req)
                     if results:
                         return results
                 except Exception:
@@ -201,7 +201,7 @@ def _resolve(
                 req_type=req_type,
                 ignore_platform=pbi.resolver_ignore_platform,
             )
-            return resolver.resolve_from_provider(provider, req)
+            return resolver.find_all_matching_from_provider(provider, req)
 
     def get_cached_resolution(
         self,
@@ -369,8 +369,8 @@ def _resolve_from_version_source(
                 constraints=self.ctx.constraints,
                 use_resolver_cache=False,
             )
-            # resolve_from_provider now returns all matching candidates
-            return resolver.resolve_from_provider(provider, req)
+            # find_all_matching_from_provider now returns all matching candidates
+            return resolver.find_all_matching_from_provider(provider, req)
         except Exception as err:
             logger.debug(f"could not resolve {req} from {version_source}: {err}")
             return None

src/fromager/resolver.py

@@ -103,7 +103,7 @@ def resolve(
         req_type=req_type,
         ignore_platform=ignore_platform,
     )
-    results = resolve_from_provider(provider, req)
+    results = find_all_matching_from_provider(provider, req)
     return results[0]
 
 
@@ -168,21 +168,37 @@ def ending(self, state: typing.Any) -> None:
         self._report("successfully resolved %r", self.req)
 
 
-def resolve_from_provider(
+def find_all_matching_from_provider(
     provider: BaseProvider, req: Requirement
 ) -> list[tuple[str, Version]]:
-    """Resolve requirement and return all matching candidates.
+    """Find all matching candidates from provider without full dependency resolution.
+
+    This function collects ALL candidates that match the requirement, rather than
+    performing full dependency resolution to find a single best candidate.
 
     Returns list of (url, version) tuples sorted by version (highest first).
+
+    IMPORTANT: This bypasses resolvelib's full resolver to collect all matching
+    candidates. This is safe ONLY because BaseProvider.get_dependencies() returns
+    an empty list (no transitive dependencies to resolve). The empty incompatibilities
+    dict means no version is ever excluded based on conflicts.
+
+    If get_dependencies() is ever extended to return actual dependencies, this
+    function must be revisited to use resolvelib's full resolution algorithm
+    (Resolver.resolve()) to properly handle dependency conflicts and backtracking.
     """
     # Get all matching candidates directly from provider
     # instead of using resolvelib's resolver which picks just one
     identifier = provider.identify(req)
     try:
+        # Bypass resolvelib's resolver to collect all matching candidates rather than
+        # just the single best one. This is safe because get_dependencies() returns []
+        # (no transitive deps to resolve). If get_dependencies() is ever extended,
+        # this must be revisited to use resolvelib's full resolution.
         candidates = provider.find_matches(
             identifier=identifier,
             requirements={identifier: [req]},
-            incompatibilities={},
+            incompatibilities={},  # Empty - safe only because no transitive deps
         )
     except resolvelib.resolvers.ResolverException as err:
         constraint = provider.constraints.get_constraint(req.name)

src/fromager/sources.py

@@ -160,7 +160,7 @@ def resolve_source(
         )
 
         # Get all matching candidates from provider
-        results = resolver.resolve_from_provider(provider, req)
+        results = resolver.find_all_matching_from_provider(provider, req)
 
         # Return highest version (first in sorted list)
         url, version = results[0]

src/fromager/wheels.py

@@ -487,7 +487,7 @@ def resolve_prebuilt_wheel(
             )
 
             # Get all matching candidates from provider
-            results = resolver.resolve_from_provider(provider, req)
+            results = resolver.find_all_matching_from_provider(provider, req)
 
             if results:
                 # Return highest version (first in sorted list)

tests/test_bootstrap_requirement_resolver.py

@@ -448,7 +448,7 @@ def test_resolve_rejects_git_urls_for_source(tmp_context: WorkContext) -> None:
         )
 
 
-@patch("fromager.resolver.resolve_from_provider")
+@patch("fromager.resolver.find_all_matching_from_provider")
 def test_resolve_allows_git_urls_for_prebuilt(
     mock_resolve: MagicMock,
     tmp_context: WorkContext,
@@ -476,7 +476,7 @@ def test_resolve_allows_git_urls_for_prebuilt(
     assert version == Version("1.0")
 
 
-@patch("fromager.resolver.resolve_from_provider")
+@patch("fromager.resolver.find_all_matching_from_provider")
 def test_resolve_auto_routes_to_prebuilt(
     mock_resolve: MagicMock,
     tmp_context: WorkContext,
@@ -514,7 +514,7 @@ def test_resolve_auto_routes_to_prebuilt(
         assert version == Version("1.0")
 
 
-@patch("fromager.resolver.resolve_from_provider")
+@patch("fromager.resolver.find_all_matching_from_provider")
 def test_resolve_auto_routes_to_source(
     mock_resolve: MagicMock,
     tmp_context: WorkContext,
@@ -554,7 +554,7 @@ def test_resolve_auto_routes_to_source(
         assert version == Version("2.0")
 
 
-@patch("fromager.resolver.resolve_from_provider")
+@patch("fromager.resolver.find_all_matching_from_provider")
 def test_resolve_prebuilt_after_source_uses_separate_cache(
     mock_resolve: MagicMock,
     tmp_context: WorkContext,

tests/test_resolver.py

@@ -1213,7 +1213,9 @@ def test_custom_resolver_error_message_missing_tag() -> None:
         provider = resolver.GitHubTagProvider(organization="test-org", repo="test-repo")
 
         with pytest.raises(resolvelib.resolvers.ResolverException) as exc_info:
-            resolver.resolve_from_provider(provider, Requirement("test-package==1.0.0"))
+            resolver.find_all_matching_from_provider(
+                provider, Requirement("test-package==1.0.0")
+            )
 
         error_message = str(exc_info.value)
         assert (
@@ -1249,7 +1251,9 @@ def custom_resolver_provider(
         provider = custom_resolver_provider()
 
         with pytest.raises(resolvelib.resolvers.ResolverException) as exc_info:
-            resolver.resolve_from_provider(provider, Requirement("test-package==1.0.0"))
+            resolver.find_all_matching_from_provider(
+                provider, Requirement("test-package==1.0.0")
+            )
 
         error_message = str(exc_info.value)
         # After fix for issue #858, the error message should indicate that a GitHub resolver was used

tests/test_sources.py

@@ -23,14 +23,14 @@ def test_invalid_tarfile(mock_download_url: typing.Any, tmp_path: pathlib.Path)
         sources._download_source_check(req=req, destination_dir=fake_dir, url=fake_url)
 
 
-@patch("fromager.resolver.resolve_from_provider")
+@patch("fromager.resolver.find_all_matching_from_provider")
 @patch("fromager.sources._download_source_check")
 def test_resolve_source_from_settings(
     download_source_check: Mock,
-    resolve_from_provider: Mock,
+    find_all_matching_from_provider: Mock,
     testdata_context: context.WorkContext,
 ) -> None:
-    resolve_from_provider.return_value = [("url", Version("42.1.2"))]
+    find_all_matching_from_provider.return_value = [("url", Version("42.1.2"))]
     download_source_check.return_value = pathlib.Path("filename.zip")
     req = Requirement("test_pkg==42.1.2")
     sdist_server_url = "https://sdist.test/egg"
@@ -59,7 +59,7 @@ def test_resolve_source_from_settings(
     )
 
 
-@patch("fromager.resolver.resolve_from_provider")
+@patch("fromager.resolver.find_all_matching_from_provider")
 @patch("fromager.sources._download_source_check")
 @patch.multiple(
     packagesettings.PackageBuildInfo,
@@ -69,10 +69,10 @@ def test_resolve_source_from_settings(
 )
 def test_resolve_source_with_predefined_resolve_dist(
     download_source_check: Mock,
-    resolve_from_provider: Mock,
+    find_all_matching_from_provider: Mock,
     tmp_context: context.WorkContext,
 ) -> None:
-    resolve_from_provider.return_value = [("url", Version("1.0"))]
+    find_all_matching_from_provider.return_value = [("url", Version("1.0"))]
     download_source_check.return_value = pathlib.Path("filename")
     req = Requirement("foo==1.0")