test_bootstrapper_iterative.py

"""Tests for the iterative bootstrap implementation.

Tests cover:
- Phase class hierarchy: class variables and base class behavior
- WorkItem dataclass defaults and state accumulation
- _track_why context manager behavior
- create_unresolved_work_items helper
- Resolve.run() version expansion
- Start.run() graph addition and seen-check
- PrepareSource.run() all branches (prebuilt, source, cached, bad path)
- PrepareBuild.run() dep installation and extraction
- Build.run() conditional install and result construction
- ProcessInstallDeps.run() hooks, dep extraction, error modes
- Complete.run() cleanup
- _handle_phase_error for all three error modes
- End-to-end iterative loop with LIFO ordering
"""

from __future__ import annotations

import concurrent.futures
import logging
import pathlib
import typing
from unittest.mock import Mock, call, patch

import pytest
from packaging.requirements import Requirement
from packaging.utils import canonicalize_name
from packaging.version import Version
from resolvelib.resolvers import ResolverException

from fromager import bootstrapper, build_environment
from fromager.bootstrapper._build import Build
from fromager.bootstrapper._complete import Complete
from fromager.bootstrapper._phase import Phase
from fromager.bootstrapper._prepare_build import PrepareBuild
from fromager.bootstrapper._prepare_source import PrepareSource
from fromager.bootstrapper._process_install_deps import ProcessInstallDeps
from fromager.bootstrapper._resolve import Resolve
from fromager.bootstrapper._start import Start
from fromager.bootstrapper._types import (
    BootstrapPhase,
    PreparedSourceData,
    SourceBuildResult,
)
from fromager.bootstrapper._work_item import WorkItem
from fromager.context import WorkContext
from fromager.requirements_file import RequirementType, SourceType


def _make_resolved_future(
    result: typing.Any,
) -> concurrent.futures.Future[typing.Any]:
    """Return an already-completed Future carrying *result*."""
    future: concurrent.futures.Future[typing.Any] = concurrent.futures.Future()
    future.set_result(result)
    return future


def _make_work_item(
    req: str = "testpkg",
    req_type: RequirementType = RequirementType.INSTALL,
    why_snapshot: list | None = None,
    parent: tuple | None = None,
    source_url: str | None = None,
    version: str | None = None,
    build_env: build_environment.BuildEnvironment | None = None,
    sdist_root_dir: pathlib.Path | None = None,
    unpack_dir: pathlib.Path | None = None,
    build_result: SourceBuildResult | None = None,
    build_system_deps: set[Requirement] | None = None,
    build_backend_deps: set[Requirement] | None = None,
    build_sdist_deps: set[Requirement] | None = None,
    pbi_pre_built: bool = False,
    cached_wheel_filename: pathlib.Path | None = None,
    build_sdist_only: bool = False,
) -> WorkItem:
    return WorkItem(
        req=Requirement(req),
        req_type=req_type,
        why_snapshot=why_snapshot or [],
        parent=parent,
        source_url=source_url,
        resolved_version=Version(version) if version else None,
        build_env=build_env,
        sdist_root_dir=sdist_root_dir,
        unpack_dir=unpack_dir,
        build_result=build_result,
        build_system_deps=build_system_deps if build_system_deps is not None else set(),
        build_backend_deps=build_backend_deps
        if build_backend_deps is not None
        else set(),
        build_sdist_deps=build_sdist_deps if build_sdist_deps is not None else set(),
        pbi_pre_built=pbi_pre_built,
        cached_wheel_filename=cached_wheel_filename,
        build_sdist_only=build_sdist_only,
    )


def _make_resolve_item(
    req: str = "testpkg",
    req_type: RequirementType = RequirementType.INSTALL,
    why_snapshot: list | None = None,
    parent: tuple | None = None,
) -> Resolve:
    return Resolve(
        WorkItem(
            req=Requirement(req),
            req_type=req_type,
            why_snapshot=why_snapshot or [],
            parent=parent,
        )
    )


def _make_start_item(
    req: str = "testpkg",
    req_type: RequirementType = RequirementType.INSTALL,
    source_url: str = "https://pypi.org/testpkg-1.0.tar.gz",
    version: str = "1.0",
    why_snapshot: list | None = None,
    parent: tuple | None = None,
) -> Start:
    return Start(
        WorkItem(
            req=Requirement(req),
            req_type=req_type,
            why_snapshot=why_snapshot or [],
            parent=parent,
            source_url=source_url,
            resolved_version=Version(version),
        )
    )


_PHASE_TO_CLASS: dict[BootstrapPhase, type[Phase]] = {
    BootstrapPhase.RESOLVE: Resolve,
    BootstrapPhase.START: Start,
    BootstrapPhase.PREPARE_SOURCE: PrepareSource,
    BootstrapPhase.PREPARE_BUILD: PrepareBuild,
    BootstrapPhase.BUILD: Build,
    BootstrapPhase.PROCESS_INSTALL_DEPS: ProcessInstallDeps,
    BootstrapPhase.COMPLETE: Complete,
}


def _make_build_item(
    req: str = "testpkg",
    version: str = "1.0",
    phase: BootstrapPhase = BootstrapPhase.PREPARE_SOURCE,
    source_url: str = "https://pypi.org/testpkg-1.0.tar.gz",
    build_env: build_environment.BuildEnvironment | None = None,
    sdist_root_dir: pathlib.Path | None = None,
    unpack_dir: pathlib.Path | None = None,
    build_result: SourceBuildResult | None = None,
    build_system_deps: set[Requirement] | None = None,
    build_backend_deps: set[Requirement] | None = None,
    build_sdist_deps: set[Requirement] | None = None,
    pbi_pre_built: bool = False,
    cached_wheel_filename: pathlib.Path | None = None,
    build_sdist_only: bool = False,
) -> Phase:
    wi = WorkItem(
        req=Requirement(req),
        req_type=RequirementType.INSTALL,
        why_snapshot=[],
        source_url=source_url,
        resolved_version=Version(version),
        build_env=build_env,
        sdist_root_dir=sdist_root_dir,
        unpack_dir=unpack_dir,
        build_result=build_result,
        build_system_deps=build_system_deps if build_system_deps is not None else set(),
        build_backend_deps=build_backend_deps
        if build_backend_deps is not None
        else set(),
        build_sdist_deps=build_sdist_deps if build_sdist_deps is not None else set(),
        pbi_pre_built=pbi_pre_built,
        cached_wheel_filename=cached_wheel_filename,
        build_sdist_only=build_sdist_only,
    )
    return _PHASE_TO_CLASS[phase](wi)


class TestPhaseClassVariables:
    """Verify class-variable declarations on each Phase subclass."""

    @pytest.mark.parametrize(
        "cls, expected_phase, expected_tracks_why",
        [
            (Resolve, BootstrapPhase.RESOLVE, False),
            (Start, BootstrapPhase.START, False),
            (PrepareSource, BootstrapPhase.PREPARE_SOURCE, True),
            (PrepareBuild, BootstrapPhase.PREPARE_BUILD, True),
            (Build, BootstrapPhase.BUILD, True),
            (ProcessInstallDeps, BootstrapPhase.PROCESS_INSTALL_DEPS, True),
            (Complete, BootstrapPhase.COMPLETE, True),
        ],
    )
    def test_class_variables(
        self,
        tmp_context: WorkContext,
        cls: type[Phase],
        expected_phase: BootstrapPhase,
        expected_tracks_why: bool,
    ) -> None:
        assert cls.phase == expected_phase
        assert cls.tracks_why == expected_tracks_why

    def test_str_default(self) -> None:
        wi = _make_work_item(req="mypkg")
        item = Build(wi)
        assert str(item) == "Build(mypkg)"

    def test_background_work_returns_none_by_default(
        self, tmp_context: WorkContext
    ) -> None:
        bt = bootstrapper.Bootstrapper(tmp_context)
        for cls in (PrepareBuild, Build, ProcessInstallDeps, Complete):
            wi = _make_work_item(req="testpkg", version="1.0")
            item = cls(wi)
            assert item.background_work(bt) is None, (
                f"{cls.__name__}.background_work() should return None"
            )


class TestWorkItem:
    def test_defaults_for_resolve_item(self) -> None:
        item = _make_resolve_item()
        wi = item.work_item
        assert wi.source_url is None
        assert wi.resolved_version is None
        assert wi.build_sdist_only is False
        assert wi.build_env is None
        assert wi.build_result is None
        assert wi.pbi_pre_built is False
        assert wi.build_system_deps == set()
        assert wi.build_backend_deps == set()
        assert wi.build_sdist_deps == set()

    def test_state_accumulation(self) -> None:
        item = _make_start_item()
        wi = item.work_item
        wi.pbi_pre_built = True
        wi.build_sdist_only = True
        mock_env = Mock()
        wi.build_env = mock_env
        assert wi.pbi_pre_built is True
        assert wi.build_sdist_only is True
        assert wi.build_env is mock_env


class TestTrackWhy:
    def test_noop_for_resolve_phase(self, tmp_context: WorkContext) -> None:
        bt = bootstrapper.Bootstrapper(tmp_context)
        bt.why = [(RequirementType.TOP_LEVEL, Requirement("parent"), Version("1.0"))]
        item = _make_resolve_item()

        with bt._track_why(item):
            assert len(bt.why) == 1

        assert len(bt.why) == 1

    def test_noop_for_start_phase(self, tmp_context: WorkContext) -> None:
        bt = bootstrapper.Bootstrapper(tmp_context)
        bt.why = []
        item = _make_start_item()

        with bt._track_why(item):
            assert len(bt.why) == 0

        assert len(bt.why) == 0

    def test_pushes_and_pops_for_build_phase(self, tmp_context: WorkContext) -> None:
        bt = bootstrapper.Bootstrapper(tmp_context)
        bt.why = []
        item = _make_build_item(phase=BootstrapPhase.PREPARE_SOURCE)
        wi = item.work_item

        with bt._track_why(item):
            assert len(bt.why) == 1
            assert bt.why[0][1] == wi.req
            assert bt.why[0][2] == wi.resolved_version

        assert len(bt.why) == 0

    def test_pops_on_exception(self, tmp_context: WorkContext) -> None:
        bt = bootstrapper.Bootstrapper(tmp_context)
        bt.why = []
        item = _make_build_item(phase=BootstrapPhase.BUILD)

        with pytest.raises(ValueError, match="boom"):
            with bt._track_why(item):
                assert len(bt.why) == 1
                raise ValueError("boom")

        assert len(bt.why) == 0


class TestCreateUnresolvedWorkItems:
    def test_creates_resolve_phase_items(self, tmp_context: WorkContext) -> None:
        bt = bootstrapper.Bootstrapper(tmp_context)
        deps = [Requirement("dep-a"), Requirement("dep-b")]

        items = bt.create_unresolved_work_items(
            deps, RequirementType.BUILD_SYSTEM, Requirement("parent"), Version("1.0")
        )

        assert len(items) == 2
        for item in items:
            assert isinstance(item, Resolve)
            assert item.phase == BootstrapPhase.RESOLVE
            assert item.work_item.req_type == RequirementType.BUILD_SYSTEM
            assert item.work_item.parent == (Requirement("parent"), Version("1.0"))
            assert item.work_item.source_url is None
            assert item.work_item.resolved_version is None

    def test_captures_why_snapshot(self, tmp_context: WorkContext) -> None:
        bt = bootstrapper.Bootstrapper(tmp_context)
        bt.why = [(RequirementType.TOP_LEVEL, Requirement("root"), Version("2.0"))]

        items = bt.create_unresolved_work_items(
            [Requirement("dep")],
            RequirementType.INSTALL,
            Requirement("parent"),
            Version("1.0"),
        )

        assert len(items) == 1
        assert items[0].work_item.why_snapshot == bt.why
        # Verify it's a copy, not a reference
        bt.why.append((RequirementType.INSTALL, Requirement("other"), Version("3.0")))
        assert len(items[0].work_item.why_snapshot) == 1

    def test_sorts_by_name(self, tmp_context: WorkContext) -> None:
        bt = bootstrapper.Bootstrapper(tmp_context)
        deps = [Requirement("zebra"), Requirement("alpha"), Requirement("middle")]

        items = bt.create_unresolved_work_items(
            deps, RequirementType.INSTALL, Requirement("p"), Version("1.0")
        )

        names = [str(item.work_item.req.name) for item in items]
        assert names == ["alpha", "middle", "zebra"]

    def test_empty_deps(self, tmp_context: WorkContext) -> None:
        bt = bootstrapper.Bootstrapper(tmp_context)
        items = bt.create_unresolved_work_items(
            [], RequirementType.INSTALL, Requirement("p"), Version("1.0")
        )
        assert items == []


class TestPhaseResolve:
    def test_single_version(self, tmp_context: WorkContext) -> None:
        bt = bootstrapper.Bootstrapper(tmp_context)
        item = _make_resolve_item()
        wi = item.work_item
        wi.parent = (Requirement("parent"), Version("2.0"))
        item.bg_future = _make_resolved_future(
            [("https://pypi.org/testpkg-1.0.tar.gz", Version("1.0"))]
        )

        result = item.run(bt)

        assert len(result) == 1
        assert isinstance(result[0], Start)
        assert result[0].work_item.source_url == "https://pypi.org/testpkg-1.0.tar.gz"
        assert result[0].work_item.resolved_version == Version("1.0")
        assert result[0].work_item.parent == wi.parent

    def test_multiple_versions(self, tmp_context: WorkContext) -> None:
        bt = bootstrapper.Bootstrapper(tmp_context, multiple_versions=True)
        item = _make_resolve_item()
        item.bg_future = _make_resolved_future(
            [
                ("https://pypi.org/testpkg-2.0.tar.gz", Version("2.0")),
                ("https://pypi.org/testpkg-1.0.tar.gz", Version("1.0")),
            ]
        )

        result = item.run(bt)

        assert len(result) == 2
        # Reversed so highest version ends up on top of stack (last element)
        assert result[0].work_item.resolved_version == Version("1.0")
        assert result[1].work_item.resolved_version == Version("2.0")

    def test_empty_resolution_raises(self, tmp_context: WorkContext) -> None:
        bt = bootstrapper.Bootstrapper(tmp_context)
        item = _make_resolve_item()
        item.bg_future = _make_resolved_future([])

        with pytest.raises(RuntimeError, match="Could not resolve"):
            item.run(bt)

    def test_preserves_why_snapshot(self, tmp_context: WorkContext) -> None:
        bt = bootstrapper.Bootstrapper(tmp_context)
        snapshot = [(RequirementType.TOP_LEVEL, Requirement("root"), Version("1.0"))]
        item = _make_resolve_item(why_snapshot=list(snapshot))
        item.bg_future = _make_resolved_future([("url", Version("1.0"))])

        result = item.run(bt)

        assert result[0].work_item.why_snapshot == snapshot

    def test_filters_cached_versions_in_multiple_versions_mode(
        self, tmp_context: WorkContext
    ) -> None:
        """Cached versions are filtered out before creating Starts."""
        bt = bootstrapper.Bootstrapper(tmp_context, multiple_versions=True)
        item = _make_resolve_item()
        item.bg_future = _make_resolved_future(
            [
                ("url-3.0", Version("3.0")),
                ("url-2.0", Version("2.0")),
                ("url-1.0", Version("1.0")),
            ]
        )

        def mock_cache(
            ctx: object, cache_url: object, req: Requirement, version: Version
        ) -> tuple:
            if str(version) == "2.0":
                return (tmp_context.work_dir / "pkg-2.0-py3-none-any.whl", None)
            return (None, None)

        with patch(
            "fromager.bootstrapper._cache.find_cached_wheel", side_effect=mock_cache
        ):
            result = item.run(bt)

        assert len(result) == 2
        versions = {str(it.work_item.resolved_version) for it in result}
        assert versions == {"1.0", "3.0"}

    def test_all_cached_keeps_highest_version(self, tmp_context: WorkContext) -> None:
        """If all versions are cached, keeps the highest for dependency discovery."""
        bt = bootstrapper.Bootstrapper(tmp_context, multiple_versions=True)
        item = _make_resolve_item()
        item.bg_future = _make_resolved_future(
            [
                ("url-3.0", Version("3.0")),
                ("url-2.0", Version("2.0")),
                ("url-1.0", Version("1.0")),
            ]
        )

        with patch(
            "fromager.bootstrapper._cache.find_cached_wheel",
            return_value=(tmp_context.work_dir / "cached.whl", None),
        ):
            result = item.run(bt)

        assert len(result) == 1
        assert result[0].work_item.resolved_version == Version("3.0")

    def test_no_filtering_in_single_version_mode(
        self, tmp_context: WorkContext
    ) -> None:
        """Cache filtering does not apply in single version mode."""
        bt = bootstrapper.Bootstrapper(tmp_context, multiple_versions=False)
        item = _make_resolve_item()
        item.bg_future = _make_resolved_future([("url-1.0", Version("1.0"))])

        with patch("fromager.bootstrapper._cache.find_cached_wheel") as mock_cache:
            result = item.run(bt)

        assert len(result) == 1
        mock_cache.assert_not_called()

    def test_empty_resolution_raises_runtime_error(
        self, tmp_context: WorkContext
    ) -> None:
        """Empty resolution raises RuntimeError regardless of mode."""
        for multi in (False, True):
            bt = bootstrapper.Bootstrapper(tmp_context, multiple_versions=multi)
            item = _make_resolve_item()
            item.bg_future = _make_resolved_future([])

            with pytest.raises(RuntimeError, match="Could not resolve"):
                item.run(bt)

    def test_filters_failed_versions_in_multiple_versions_mode(
        self, tmp_context: WorkContext
    ) -> None:
        """Previously failed versions are excluded before creating Starts."""
        bt = bootstrapper.Bootstrapper(tmp_context, multiple_versions=True)
        item = _make_resolve_item()

        bt._failed_versions[(canonicalize_name("testpkg"), "2.0")] = RuntimeError(
            "boom"
        )
        item.bg_future = _make_resolved_future(
            [
                ("url-3.0", Version("3.0")),
                ("url-2.0", Version("2.0")),
                ("url-1.0", Version("1.0")),
            ]
        )

        with patch(
            "fromager.bootstrapper._cache.find_cached_wheel", return_value=(None, None)
        ):
            result = item.run(bt)

        versions = {str(it.work_item.resolved_version) for it in result}
        assert versions == {"1.0", "3.0"}

    def test_failed_version_filter_does_not_apply_in_single_version_mode(
        self, tmp_context: WorkContext
    ) -> None:
        """Failed-version filtering only applies in multiple_versions mode."""
        bt = bootstrapper.Bootstrapper(tmp_context, multiple_versions=False)
        item = _make_resolve_item()

        bt._failed_versions[(canonicalize_name("testpkg"), "1.0")] = RuntimeError(
            "boom"
        )
        item.bg_future = _make_resolved_future([("url-1.0", Version("1.0"))])

        result = item.run(bt)

        assert len(result) == 1
        assert result[0].work_item.resolved_version == Version("1.0")

    def test_all_versions_failed_raises_runtime_error(
        self, tmp_context: WorkContext
    ) -> None:
        """Raises RuntimeError when all resolved versions already failed."""
        bt = bootstrapper.Bootstrapper(tmp_context, multiple_versions=True)
        item = _make_resolve_item()

        bt._failed_versions[(canonicalize_name("testpkg"), "1.0")] = RuntimeError(
            "boom"
        )
        item.bg_future = _make_resolved_future([("url-1.0", Version("1.0"))])

        with pytest.raises(RuntimeError, match="failed previously"):
            item.run(bt)

    def test_bg_future_exception_propagates(self, tmp_context: WorkContext) -> None:
        """Exceptions from the background resolver thread are surfaced by run()."""
        bt = bootstrapper.Bootstrapper(tmp_context)
        item = _make_resolve_item()
        future: concurrent.futures.Future[list[tuple[str, Version]]] = (
            concurrent.futures.Future()
        )
        future.set_exception(ValueError("resolver exploded"))
        item.bg_future = future

        with pytest.raises(ValueError, match="resolver exploded"):
            item.run(bt)


class TestPhaseStart:
    def test_new_item_advances_to_prepare_source(
        self, tmp_context: WorkContext
    ) -> None:
        bt = bootstrapper.Bootstrapper(tmp_context)
        bt.why = []
        item = _make_start_item()

        result = item.run(bt)

        assert len(result) == 1
        assert isinstance(result[0], PrepareSource)
        assert result[0].work_item is item.work_item

    def test_already_seen_returns_empty(self, tmp_context: WorkContext) -> None:
        bt = bootstrapper.Bootstrapper(tmp_context)
        bt.why = []
        item = _make_start_item()
        wi = item.work_item

        # Mark as seen first
        assert wi.resolved_version is not None
        bt.mark_as_seen(wi.req, wi.resolved_version)

        result = item.run(bt)

        assert result == []

    def test_adds_to_graph_for_non_toplevel(self, tmp_context: WorkContext) -> None:
        bt = bootstrapper.Bootstrapper(tmp_context)
        bt.why = []
        item = _make_start_item(req_type=RequirementType.INSTALL)

        item.run(bt)

        key = f"{canonicalize_name('testpkg')}==1.0"
        assert key in tmp_context.dependency_graph.nodes

    def test_skips_graph_for_toplevel(self, tmp_context: WorkContext) -> None:
        bt = bootstrapper.Bootstrapper(tmp_context)
        bt.why = []
        item = _make_start_item(req_type=RequirementType.TOP_LEVEL)

        item.run(bt)

        key = f"{canonicalize_name('testpkg')}==1.0"
        assert key not in tmp_context.dependency_graph.nodes

    def test_sdist_only_set_for_non_build_requirement(
        self, tmp_context: WorkContext
    ) -> None:
        bt = bootstrapper.Bootstrapper(tmp_context, sdist_only=True)
        bt.why = []
        item = _make_start_item(req_type=RequirementType.INSTALL)

        item.run(bt)

        assert item.work_item.build_sdist_only is True

    def test_sdist_only_not_set_for_build_requirement(
        self, tmp_context: WorkContext
    ) -> None:
        bt = bootstrapper.Bootstrapper(tmp_context, sdist_only=True)
        bt.why = []
        item = _make_start_item(req_type=RequirementType.BUILD_SYSTEM)

        item.run(bt)

        assert item.work_item.build_sdist_only is False

    def test_marks_as_seen(self, tmp_context: WorkContext) -> None:
        bt = bootstrapper.Bootstrapper(tmp_context)
        bt.why = []
        item = _make_start_item()
        wi = item.work_item
        assert wi.resolved_version is not None

        assert not bt.has_been_seen(wi.req, wi.resolved_version)
        item.run(bt)
        assert bt.has_been_seen(wi.req, wi.resolved_version)

    def test_sets_pbi_pre_built_before_prepare_source(
        self, tmp_context: WorkContext
    ) -> None:
        """pbi_pre_built is set on work_item before PrepareSource is constructed."""
        bt = bootstrapper.Bootstrapper(tmp_context)
        bt.why = []
        item = _make_start_item()

        with patch.object(
            tmp_context,
            "package_build_info",
            return_value=Mock(pre_built=True),
        ):
            result = item.run(bt)

        assert len(result) == 1
        assert isinstance(result[0], PrepareSource)
        assert result[0].work_item.pbi_pre_built is True


class TestComplete:
    def test_calls_clean_build_dirs(self, tmp_context: WorkContext) -> None:
        bt = bootstrapper.Bootstrapper(tmp_context)
        mock_sdist_root = tmp_context.work_dir / "pkg-1.0" / "pkg-1.0"
        mock_env = Mock()
        build_result = SourceBuildResult(
            wheel_filename=None,
            sdist_filename=None,
            unpack_dir=tmp_context.work_dir,
            sdist_root_dir=mock_sdist_root,
            build_env=mock_env,
            source_type=SourceType.SDIST,
        )
        item = _make_build_item(phase=BootstrapPhase.COMPLETE)
        item.work_item.build_result = build_result

        with patch.object(tmp_context, "clean_build_dirs") as mock_clean:
            result = item.run(bt)

        assert result == []
        mock_clean.assert_called_once_with(mock_sdist_root, mock_env)

    def test_no_build_result_skips_cleanup(self, tmp_context: WorkContext) -> None:
        bt = bootstrapper.Bootstrapper(tmp_context)
        item = _make_build_item(phase=BootstrapPhase.COMPLETE)
        item.work_item.build_result = None

        with patch.object(tmp_context, "clean_build_dirs") as mock_clean:
            result = item.run(bt)

        assert result == []
        mock_clean.assert_not_called()

    def test_returns_empty_list(self, tmp_context: WorkContext) -> None:
        bt = bootstrapper.Bootstrapper(tmp_context)
        item = _make_build_item(phase=BootstrapPhase.COMPLETE)
        assert item.run(bt) == []


class TestEnrichResolutionError:
    """Tests for _enrich_resolution_error, used by _handle_phase_error."""

    def _why_snapshot(self) -> list[tuple[RequirementType, Requirement, Version]]:
        return [
            (RequirementType.TOP_LEVEL, Requirement("its-hub"), Version("1.0")),
            (RequirementType.INSTALL, Requirement("reward-hub"), Version("2.0")),
            (RequirementType.INSTALL, Requirement("vllm"), Version("3.0")),
        ]

    def test_resolver_exception_gets_dependency_chain(
        self, tmp_context: WorkContext
    ) -> None:
        """Regression test for #1214: name the whole chain, not just the

        top-level package.
        """
        bt = bootstrapper.Bootstrapper(tmp_context)
        item = _make_resolve_item(
            req="flashinfer-python==0.6.8.post1", why_snapshot=self._why_snapshot()
        )
        err = ResolverException("found no match")

        enriched = bt._enrich_resolution_error(item, err)

        assert isinstance(enriched, ResolverException)
        assert str(enriched) == (
            "found no match (dependency chain: its-hub==1.0 -> "
            "reward-hub==2.0 -> vllm==3.0 -> flashinfer-python==0.6.8.post1)"
        )

    def test_runtime_error_gets_dependency_chain(
        self, tmp_context: WorkContext
    ) -> None:
        """Regression test for a gap in the earlier fix: a plain RuntimeError

        (e.g. "Could not resolve any versions for ...") also gets the chain,
        not just ResolverException.
        """
        bt = bootstrapper.Bootstrapper(tmp_context)
        item = _make_resolve_item(
            req="flashinfer-python==0.6.8.post1", why_snapshot=self._why_snapshot()
        )
        err = RuntimeError("Could not resolve any versions for flashinfer-python")

        enriched = bt._enrich_resolution_error(item, err)

        assert isinstance(enriched, RuntimeError)
        assert str(enriched) == (
            "Could not resolve any versions for flashinfer-python "
            "(dependency chain: its-hub==1.0 -> reward-hub==2.0 -> "
            "vllm==3.0 -> flashinfer-python==0.6.8.post1)"
        )

    def test_unknown_exception_type_falls_back_to_runtime_error(
        self, tmp_context: WorkContext
    ) -> None:
        """`type(err)(msg)` isn't safe for arbitrary exception classes, so an

        unrecognized type is wrapped in a RuntimeError that keeps the
        original type name visible, instead of risking a TypeError trying
        to reconstruct it.
        """
        bt = bootstrapper.Bootstrapper(tmp_context)
        item = _make_resolve_item(
            req="flashinfer-python==0.6.8.post1", why_snapshot=self._why_snapshot()
        )
        err = ValueError("some unexpected failure")

        enriched = bt._enrich_resolution_error(item, err)

        assert isinstance(enriched, RuntimeError)
        assert "ValueError: some unexpected failure" in str(enriched)
        assert "dependency chain: its-hub==1.0" in str(enriched)

    def test_no_chain_returns_original_object_unchanged(
        self, tmp_context: WorkContext
    ) -> None:
        """Top-level requirements have no chain, so the original exception

        object is returned as-is (identity preserved, nothing reconstructed).
        """
        bt = bootstrapper.Bootstrapper(tmp_context)
        item = _make_resolve_item()  # default why_snapshot=[]
        err = ResolverException("found no match")

        enriched = bt._enrich_resolution_error(item, err)

        assert enriched is err

    def test_non_resolve_phase_returns_original_object_unchanged(
        self, tmp_context: WorkContext
    ) -> None:
        """Only RESOLVE-phase failures get a chain suffix."""
        bt = bootstrapper.Bootstrapper(tmp_context)
        item = _make_build_item(phase=BootstrapPhase.BUILD)
        item.work_item.why_snapshot = self._why_snapshot()
        err = RuntimeError("build failed")

        enriched = bt._enrich_resolution_error(item, err)

        assert enriched is err

    def test_enriched_exception_chains_via_context_not_cause(
        self, tmp_context: WorkContext
    ) -> None:
        """When actually raised (not just constructed), the enriched

        exception must carry the original as `__context__` (implicit
        chaining, preserves the real traceback for `exc_info=True`
        logging) while leaving `__cause__` unset, so
        `__main__._format_exception()` - which only follows `__cause__` -
        doesn't print the original message a second time via
        "... because ...". See #1243 for that formatter's own,
        independent duplication bug.
        """
        from fromager import __main__

        bt = bootstrapper.Bootstrapper(tmp_context)
        item = _make_resolve_item(
            req="flashinfer-python==0.6.8.post1", why_snapshot=self._why_snapshot()
        )
        original = ResolverException("found no match")

        try:
            raise original
        except ResolverException as caught:
            enriched = bt._enrich_resolution_error(item, caught)
            try:
                raise enriched
            except ResolverException as raised:
                final = raised

        assert final.__cause__ is None
        assert final.__context__ is original
        formatted = __main__._format_exception(final)
        assert formatted.count("found no match") == 1


class TestHandlePhaseError:
    # -- RESOLVE phase errors --

    def test_resolve_error_in_test_mode_records_failure(
        self, tmp_context: WorkContext
    ) -> None:
        bt = bootstrapper.Bootstrapper(tmp_context, test_mode=True)
        item = _make_resolve_item()
        err = RuntimeError("resolution failed")

        result = bt._handle_phase_error(item, err)

        assert result == []
        assert len(bt.failed_packages) == 1
        assert bt.failed_packages[0]["failure_type"] == "resolution"
        assert bt.failed_packages[0]["version"] is None

    def test_resolve_error_in_normal_mode_raises(
        self, tmp_context: WorkContext
    ) -> None:
        bt = bootstrapper.Bootstrapper(tmp_context)
        item = _make_resolve_item()
        err = RuntimeError("resolution failed")

        with pytest.raises(RuntimeError, match="resolution failed"):
            try:
                raise err
            except RuntimeError:
                bt._handle_phase_error(item, err)

    def test_resolve_error_in_multiple_versions_mode_continues(
        self, tmp_context: WorkContext
    ) -> None:
        """RESOLVE failures in multiple versions mode are recorded, not raised."""
        bt = bootstrapper.Bootstrapper(tmp_context, multiple_versions=True)
        item = _make_resolve_item()
        err = RuntimeError("resolution failed")

        try:
            raise err
        except RuntimeError:
            result = bt._handle_phase_error(item, err)

        assert result == []
        assert len(bt._failed_versions) == 1
        key = (canonicalize_name("testpkg"), "unresolved")
        assert key in bt._failed_versions
        assert bt._failed_versions[key] is err

    def test_resolve_error_enriched_before_test_mode_record(
        self, tmp_context: WorkContext
    ) -> None:
        """Gap identified in review: test mode must record the enriched

        message, not the raw one, so `failed_packages[].exception_message`
        shows the real dependency chain.
        """
        bt = bootstrapper.Bootstrapper(tmp_context, test_mode=True)
        why_snapshot = [
            (RequirementType.TOP_LEVEL, Requirement("its-hub"), Version("1.0")),
        ]
        item = _make_resolve_item(
            req="flashinfer-python==0.6.8.post1", why_snapshot=why_snapshot
        )
        err = ResolverException("found no match")

        bt._handle_phase_error(item, err)

        assert len(bt.failed_packages) == 1
        assert (
            "dependency chain: its-hub==1.0"
            in (bt.failed_packages[0]["exception_message"])
        )

    def test_resolve_error_enriched_before_multiple_versions_record(
        self, tmp_context: WorkContext
    ) -> None:
        """Gap identified in review: multiple-versions mode must record the

        enriched message too.
        """
        bt = bootstrapper.Bootstrapper(tmp_context, multiple_versions=True)
        why_snapshot = [
            (RequirementType.TOP_LEVEL, Requirement("its-hub"), Version("1.0")),
        ]
        item = _make_resolve_item(
            req="flashinfer-python==0.6.8.post1", why_snapshot=why_snapshot
        )
        err = ResolverException("found no match")

        bt._handle_phase_error(item, err)

        key = (canonicalize_name("flashinfer-python"), "unresolved")
        assert "dependency chain: its-hub==1.0" in str(bt._failed_versions[key])

    def test_resolve_error_enriched_before_normal_mode_raise(
        self, tmp_context: WorkContext
    ) -> None:
        """Gap this feature originally targeted: a plain RuntimeError

        ("Could not resolve any versions...") also gets the chain in
        normal (fail-fast) mode, not just ResolverException.
        """
        bt = bootstrapper.Bootstrapper(tmp_context)
        why_snapshot = [
            (RequirementType.TOP_LEVEL, Requirement("its-hub"), Version("1.0")),
        ]
        item = _make_resolve_item(
            req="flashinfer-python==0.6.8.post1", why_snapshot=why_snapshot
        )
        err = RuntimeError("Could not resolve any versions for flashinfer-python")

        with pytest.raises(RuntimeError, match=r"dependency chain: its-hub==1\.0"):
            try:
                raise err
            except RuntimeError:
                bt._handle_phase_error(item, err)

    # -- Build phase errors in test mode --

    def test_build_phase_test_mode_fallback_success(
        self, tmp_context: WorkContext
    ) -> None:
        bt = bootstrapper.Bootstrapper(tmp_context, test_mode=True)
        item = _make_build_item(phase=BootstrapPhase.PREPARE_SOURCE)
        item.work_item.pbi_pre_built = False
        err = RuntimeError("build failed")

        mock_fallback = Mock(spec=SourceBuildResult)
        with patch.object(bt, "_handle_test_mode_failure", return_value=mock_fallback):
            result = bt._handle_phase_error(item, err)

        assert len(result) == 1
        assert isinstance(result[0], ProcessInstallDeps)
        assert result[0].work_item is item.work_item
        assert result[0].work_item.build_result is mock_fallback
        assert len(bt.failed_packages) == 0

    def test_build_phase_test_mode_fallback_failure(
        self, tmp_context: WorkContext
    ) -> None:
        bt = bootstrapper.Bootstrapper(tmp_context, test_mode=True)
        item = _make_build_item(phase=BootstrapPhase.BUILD)
        item.work_item.pbi_pre_built = False
        err = RuntimeError("build failed")

        with patch.object(bt, "_handle_test_mode_failure", return_value=None):
            result = bt._handle_phase_error(item, err)

        assert result == []
        assert len(bt.failed_packages) == 1
        assert bt.failed_packages[0]["failure_type"] == "bootstrap"

    def test_build_phase_test_mode_prebuilt_skips_fallback(
        self, tmp_context: WorkContext
    ) -> None:
        bt = bootstrapper.Bootstrapper(tmp_context, test_mode=True)
        item = _make_build_item(phase=BootstrapPhase.PREPARE_SOURCE)
        item.work_item.pbi_pre_built = True
        err = RuntimeError("download failed")

        result = bt._handle_phase_error(item, err)

        assert result == []
        assert len(bt.failed_packages) == 1
        assert bt.failed_packages[0]["failure_type"] == "bootstrap"

    def test_non_build_phase_test_mode_records_failure(
        self, tmp_context: WorkContext
    ) -> None:
        bt = bootstrapper.Bootstrapper(tmp_context, test_mode=True)
        item = _make_build_item(phase=BootstrapPhase.PROCESS_INSTALL_DEPS)
        err = RuntimeError("hook failed")

        result = bt._handle_phase_error(item, err)

        assert result == []
        assert len(bt.failed_packages) == 1
        assert bt.failed_packages[0]["failure_type"] == "bootstrap"

    # -- Multiple versions mode errors --

    def test_multiple_versions_records_and_removes_from_graph(
        self, tmp_context: WorkContext
    ) -> None:
        bt = bootstrapper.Bootstrapper(tmp_context, multiple_versions=True)
        item = _make_build_item(phase=BootstrapPhase.BUILD)
        wi = item.work_item
        assert wi.resolved_version is not None
        assert wi.source_url is not None
        err = ValueError("build failed")

        # Add to graph first so remove_dependency has something to remove
        tmp_context.dependency_graph.add_dependency(
            parent_name=None,
            parent_version=None,
            req_type=RequirementType.TOP_LEVEL,
            req=wi.req,
            req_version=wi.resolved_version,
            download_url=wi.source_url,
            pre_built=False,
        )
        # Mark as seen
        bt.mark_as_seen(wi.req, wi.resolved_version)

        result = bt._handle_phase_error(item, err)

        assert result == []
        # Failure recorded
        assert len(bt._failed_versions) == 1
        assert (canonicalize_name("testpkg"), "1.0") in bt._failed_versions
        # Removed from graph
        key = f"{canonicalize_name('testpkg')}==1.0"
        assert key not in tmp_context.dependency_graph.nodes
        # Seen markers cleared
        assert not bt.has_been_seen(wi.req, wi.resolved_version)
        assert not bt.has_been_seen(wi.req, wi.resolved_version, sdist_only=True)

    def test_multiple_versions_logs_phase(
        self, tmp_context: WorkContext, caplog: pytest.LogCaptureFixture
    ) -> None:
        bt = bootstrapper.Bootstrapper(tmp_context, multiple_versions=True)
        item = _make_build_item(phase=BootstrapPhase.PREPARE_BUILD)
        err = ValueError("compile error")

        bt._handle_phase_error(item, err)

        assert "prepare-build phase" in caplog.text
        assert "compile error" in caplog.text

    # -- Normal mode errors --

    def test_normal_mode_raises(self, tmp_context: WorkContext) -> None:
        bt = bootstrapper.Bootstrapper(tmp_context)
        item = _make_build_item(phase=BootstrapPhase.BUILD)
        err = RuntimeError("build failed")

        with pytest.raises(RuntimeError, match="build failed"):
            try:
                raise err
            except RuntimeError:
                bt._handle_phase_error(item, err)


class TestIterativeBootstrapLoop:
    def test_full_lifecycle_source_package(self, tmp_context: WorkContext) -> None:
        """Drive a package through RESOLVE -> START -> ... -> COMPLETE."""
        bt = bootstrapper.Bootstrapper(tmp_context)

        phases_visited: list[BootstrapPhase] = []
        original_resolve_run = Resolve.run
        original_start_run = Start.run

        def resolve_run(
            self: Resolve, bt_arg: bootstrapper.Bootstrapper
        ) -> list[Phase]:
            phases_visited.append(type(self).phase)
            return original_resolve_run(self, bt_arg)

        def start_run(self: Start, bt_arg: bootstrapper.Bootstrapper) -> list[Phase]:
            phases_visited.append(type(self).phase)
            return original_start_run(self, bt_arg)

        def prepare_source_run(
            self: PrepareSource, bt_arg: bootstrapper.Bootstrapper
        ) -> list[Phase]:
            phases_visited.append(type(self).phase)
            wi = self.work_item
            wi.build_env = Mock()
            wi.sdist_root_dir = tmp_context.work_dir / "pkg-1.0" / "pkg-1.0"
            return [PrepareBuild(wi)]

        def prepare_build_run(
            self: PrepareBuild, bt_arg: bootstrapper.Bootstrapper
        ) -> list[Phase]:
            phases_visited.append(type(self).phase)
            return [Build(self.work_item)]

        def build_run(self: Build, bt_arg: bootstrapper.Bootstrapper) -> list[Phase]:
            phases_visited.append(type(self).phase)
            wi = self.work_item
            wi.build_result = SourceBuildResult(
                wheel_filename=None,
                sdist_filename=None,
                unpack_dir=tmp_context.work_dir,
                sdist_root_dir=None,
                build_env=None,
                source_type=SourceType.SDIST,
            )
            return [ProcessInstallDeps(wi)]

        def process_install_deps_run(
            self: ProcessInstallDeps, bt_arg: bootstrapper.Bootstrapper
        ) -> list[Phase]:
            phases_visited.append(type(self).phase)
            return [Complete(self.work_item)]

        def complete_run(
            self: Complete, bt_arg: bootstrapper.Bootstrapper
        ) -> list[Phase]:
            phases_visited.append(type(self).phase)
            return []

        with (
            patch.object(Resolve, "run", resolve_run),
            patch.object(Start, "run", start_run),
            patch.object(PrepareSource, "run", prepare_source_run),
            patch.object(PrepareBuild, "run", prepare_build_run),
            patch.object(Build, "run", build_run),
            patch.object(ProcessInstallDeps, "run", process_install_deps_run),
            patch.object(Complete, "run", complete_run),
            patch.object(
                bt._resolver,
                "resolve",
                return_value=[("https://pypi.org/pkg-1.0.tar.gz", Version("1.0"))],
            ),
        ):
            bt._bootstrap_one(Requirement("pkg"), RequirementType.TOP_LEVEL)

        assert phases_visited == [
            BootstrapPhase.RESOLVE,
            BootstrapPhase.START,
            BootstrapPhase.PREPARE_SOURCE,
            BootstrapPhase.PREPARE_BUILD,
            BootstrapPhase.BUILD,
            BootstrapPhase.PROCESS_INSTALL_DEPS,
            BootstrapPhase.COMPLETE,
        ]

    def test_lifo_ordering_deps_before_continuation(
        self, tmp_context: WorkContext
    ) -> None:
        """Verify dependencies are processed before the parent continues."""
        bt = bootstrapper.Bootstrapper(tmp_context)

        processing_order: list[tuple[str, str]] = []
        original_resolve_run = Resolve.run
        original_start_run = Start.run

        def resolve_run(
            self: Resolve, bt_arg: bootstrapper.Bootstrapper
        ) -> list[Phase]:
            processing_order.append(
                (str(self.work_item.req.name), str(type(self).phase))
            )
            return original_resolve_run(self, bt_arg)

        def start_run(self: Start, bt_arg: bootstrapper.Bootstrapper) -> list[Phase]:
            processing_order.append(
                (str(self.work_item.req.name), str(type(self).phase))
            )
            return original_start_run(self, bt_arg)

        def prepare_source_run(
            self: PrepareSource, bt_arg: bootstrapper.Bootstrapper
        ) -> list[Phase]:
            phase_name = str(type(self).phase)
            req_name = str(self.work_item.req.name)
            processing_order.append((req_name, phase_name))
            wi = self.work_item
            if req_name == "parent":
                assert wi.resolved_version is not None
                dep_item = Resolve(
                    WorkItem(
                        req=Requirement("child"),
                        req_type=RequirementType.BUILD_SYSTEM,
                        why_snapshot=[],
                        parent=(wi.req, wi.resolved_version),
                    )
                )
                return [Complete(wi), dep_item]
            return []

        def complete_run(
            self: Complete, bt_arg: bootstrapper.Bootstrapper
        ) -> list[Phase]:
            processing_order.append(
                (str(self.work_item.req.name), str(type(self).phase))
            )
            return []

        # Pre-add parent to graph so child can reference it as parent
        tmp_context.dependency_graph.add_dependency(
            parent_name=None,
            parent_version=None,
            req_type=RequirementType.TOP_LEVEL,
            req=Requirement("parent"),
            req_version=Version("1.0"),
            download_url="https://pypi.org/pkg-1.0.tar.gz",
            pre_built=False,
        )

        with (
            patch.object(Resolve, "run", resolve_run),
            patch.object(Start, "run", start_run),
            patch.object(PrepareSource, "run", prepare_source_run),
            patch.object(Complete, "run", complete_run),
            patch.object(
                bt._resolver,
                "resolve",
                return_value=[("https://pypi.org/pkg-1.0.tar.gz", Version("1.0"))],
            ),
        ):
            bt._bootstrap_one(Requirement("parent"), RequirementType.TOP_LEVEL)

        # child's RESOLVE and START must appear before parent's COMPLETE
        req_phase_pairs = [
            (name, phase)
            for name, phase in processing_order
            if name in ("parent", "child")
        ]

        parent_complete_idx = next(
            i
            for i, (n, p) in enumerate(req_phase_pairs)
            if n == "parent" and p == "complete"
        )
        child_indices = [i for i, (n, _) in enumerate(req_phase_pairs) if n == "child"]

        assert all(idx < parent_complete_idx for idx in child_indices), (
            f"child must be processed before parent completes: {req_phase_pairs}"
        )

    def test_multiple_versions_error_isolation(self, tmp_context: WorkContext) -> None:
        """Each version fails independently without crashing the loop."""
        bt = bootstrapper.Bootstrapper(tmp_context, multiple_versions=True)

        def prepare_source_run(
            self: PrepareSource, bt_arg: bootstrapper.Bootstrapper
        ) -> list[Phase]:
            if str(self.work_item.resolved_version) == "1.5":
                raise ValueError("1.5 broken")
            return []

        with (
            patch.object(PrepareSource, "run", prepare_source_run),
            patch.object(
                bt._resolver,
                "resolve",
                return_value=[
                    ("url-2.0", Version("2.0")),
                    ("url-1.5", Version("1.5")),
                    ("url-1.0", Version("1.0")),
                ],
            ),
            patch.object(bt, "has_been_seen", return_value=False),
        ):
            bt._bootstrap_one(Requirement("pkg"), RequirementType.INSTALL)

        assert len(bt._failed_versions) == 1
        assert (canonicalize_name("pkg"), "1.5") in bt._failed_versions
        # Other versions processed successfully (in graph)
        assert f"{canonicalize_name('pkg')}==2.0" in tmp_context.dependency_graph.nodes
        assert f"{canonicalize_name('pkg')}==1.0" in tmp_context.dependency_graph.nodes

    def test_multiple_versions_resolve_failure_continues(
        self, tmp_context: WorkContext
    ) -> None:
        """RESOLVE failure for one dependency does not crash the loop."""
        bt = bootstrapper.Bootstrapper(tmp_context, multiple_versions=True)

        original_resolve_run = Resolve.run
        completed: list[str] = []

        def resolve_run(
            self: Resolve, bt_arg: bootstrapper.Bootstrapper
        ) -> list[Phase]:
            if str(self.work_item.req.name) == "bad-dep":
                raise RuntimeError("Could not resolve any versions for bad-dep")
            return original_resolve_run(self, bt_arg)

        def prepare_source_run(
            self: PrepareSource, bt_arg: bootstrapper.Bootstrapper
        ) -> list[Phase]:
            completed.append(str(self.work_item.req.name))
            return []

        with (
            patch.object(Resolve, "run", resolve_run),
            patch.object(PrepareSource, "run", prepare_source_run),
            patch.object(
                bt._resolver,
                "resolve",
                return_value=[("url-1.0", Version("1.0"))],
            ),
            patch.object(bt, "has_been_seen", return_value=False),
        ):
            bt._bootstrap_one(Requirement("good-pkg"), RequirementType.INSTALL)
            bt._bootstrap_one(Requirement("bad-dep"), RequirementType.INSTALL)
            bt._bootstrap_one(Requirement("another-good"), RequirementType.INSTALL)

        assert "good-pkg" in completed
        assert "another-good" in completed
        failed_names = [name for name, _ in bt._failed_versions]
        assert canonicalize_name("bad-dep") in failed_names

    def test_test_mode_continues_after_failure(self, tmp_context: WorkContext) -> None:
        """In test mode, failed items are recorded and processing continues."""
        bt = bootstrapper.Bootstrapper(tmp_context, test_mode=True)

        items_completed: list[str] = []

        def prepare_source_run(
            self: PrepareSource, bt_arg: bootstrapper.Bootstrapper
        ) -> list[Phase]:
            if str(self.work_item.req.name) == "fail-pkg":
                raise RuntimeError("build error")
            items_completed.append(str(self.work_item.req.name))
            return []

        with (
            patch.object(PrepareSource, "run", prepare_source_run),
            patch.object(
                bt._resolver,
                "resolve",
                return_value=[("url", Version("1.0"))],
            ),
        ):
            # Bootstrap a package that will fail
            bt._bootstrap_one(Requirement("fail-pkg"), RequirementType.TOP_LEVEL)
            # Bootstrap another that will succeed
            bt._bootstrap_one(Requirement("ok-pkg"), RequirementType.TOP_LEVEL)

        assert len(bt.failed_packages) == 1
        assert bt.failed_packages[0]["package"] == "fail-pkg"
        assert "ok-pkg" in items_completed


class TestPhasePrepareSource:
    """Tests for PrepareSource.run(): prebuilt, source, cache, and error paths."""

    def test_prebuilt_uses_background_result(self, tmp_context: WorkContext) -> None:
        """Prebuilt package uses bg_future result and advances to PROCESS_INSTALL_DEPS."""
        bt = bootstrapper.Bootstrapper(tmp_context)
        item = _make_build_item(
            phase=BootstrapPhase.PREPARE_SOURCE,
            pbi_pre_built=True,
            source_url="https://pkg.test/testpkg-1.0-py3-none-any.whl",
        )

        mock_wheel = tmp_context.work_dir / "testpkg-1.0-py3-none-any.whl"
        mock_unpack = tmp_context.work_dir / "testpkg-1.0"
        item.bg_future = _make_resolved_future(
            PreparedSourceData(wheel_filename=mock_wheel, unpack_dir=mock_unpack)
        )

        with patch.object(tmp_context.constraints, "get_constraint", return_value=None):
            result = item.run(bt)

        assert len(result) == 1
        assert isinstance(result[0], ProcessInstallDeps)
        assert result[0].work_item is item.work_item
        wi = result[0].work_item
        assert wi.build_result is not None
        assert wi.build_result.source_type == SourceType.PREBUILT
        assert wi.build_result.wheel_filename == mock_wheel
        assert wi.build_result.sdist_filename is None
        assert wi.build_result.build_env is None

    def test_source_no_cache_uses_background_result(
        self, tmp_context: WorkContext
    ) -> None:
        """Source build with no cached wheel uses bg_future result."""
        bt = bootstrapper.Bootstrapper(tmp_context)
        item = _make_build_item(phase=BootstrapPhase.PREPARE_SOURCE)

        sdist_root = tmp_context.work_dir / "testpkg-1.0" / "testpkg-1.0"
        mock_env = Mock()
        mock_dep_item = _make_resolve_item(req="setuptools")
        item.bg_future = _make_resolved_future(
            PreparedSourceData(sdist_root_dir=sdist_root)
        )

        with (
            patch.object(tmp_context.constraints, "get_constraint", return_value=None),
            patch(
                "fromager.build_environment.BuildEnvironment",
                return_value=mock_env,
            ) as mock_build_env_cls,
            patch(
                "fromager.dependencies.get_build_system_dependencies",
                return_value={Requirement("setuptools")},
            ),
            patch.object(
                bt, "create_unresolved_work_items", return_value=[mock_dep_item]
            ) as mock_create_items,
        ):
            result = item.run(bt)

        wi = item.work_item
        assert isinstance(result[0], PrepareBuild)
        assert result[0].work_item is wi
        assert wi.build_env is mock_env
        assert wi.sdist_root_dir == sdist_root
        assert wi.unpack_dir == sdist_root.parent
        assert wi.cached_wheel_filename is None
        assert result[1] is mock_dep_item
        mock_build_env_cls.assert_called_once_with(
            ctx=bt.ctx,
            req=wi.req,
            sdist_root_dir=sdist_root,
        )
        mock_create_items.assert_called_once_with(
            wi.build_system_deps,
            RequirementType.BUILD_SYSTEM,
            wi.req,
            wi.resolved_version,
        )

    def test_source_cached_wheel_uses_background_result(
        self, tmp_context: WorkContext
    ) -> None:
        """Cached wheel background result sets cached_wheel_filename and sdist_root."""
        bt = bootstrapper.Bootstrapper(tmp_context)
        item = _make_build_item(phase=BootstrapPhase.PREPARE_SOURCE)

        unpacked = tmp_context.work_dir / "testpkg-1.0"
        unpacked.mkdir(parents=True)
        cached_wheel = tmp_context.work_dir / "testpkg-1.0-py3-none-any.whl"
        mock_env = Mock()
        item.bg_future = _make_resolved_future(
            PreparedSourceData(
                sdist_root_dir=unpacked / unpacked.stem,
                cached_wheel_filename=cached_wheel,
            )
        )

        with (
            patch.object(tmp_context.constraints, "get_constraint", return_value=None),
            patch(
                "fromager.build_environment.BuildEnvironment",
                return_value=mock_env,
            ),
            patch(
                "fromager.dependencies.get_build_system_dependencies",
                return_value=set(),
            ),
            patch.object(bt, "create_unresolved_work_items", return_value=[]),
        ):
            result = item.run(bt)

        wi = item.work_item
        assert wi.cached_wheel_filename == cached_wheel
        assert wi.sdist_root_dir == unpacked / unpacked.stem
        assert isinstance(result[0], PrepareBuild)
        assert len(result) == 1

    def test_bad_sdist_root_raises_valueerror(self, tmp_context: WorkContext) -> None:
        """ValueError raised when sdist_root_dir.parent.parent != work_dir."""
        bt = bootstrapper.Bootstrapper(tmp_context)
        item = _make_build_item(phase=BootstrapPhase.PREPARE_SOURCE)

        bad_root = tmp_context.work_dir / "a" / "b" / "c"
        item.bg_future = _make_resolved_future(
            PreparedSourceData(sdist_root_dir=bad_root)
        )

        with patch.object(tmp_context.constraints, "get_constraint", return_value=None):
            with pytest.raises(ValueError, match="should be"):
                item.run(bt)

    def test_constraint_logged_when_present(
        self, tmp_context: WorkContext, caplog: pytest.LogCaptureFixture
    ) -> None:
        """Constraint presence is logged without affecting phase advancement."""
        bt = bootstrapper.Bootstrapper(tmp_context)
        item = _make_build_item(phase=BootstrapPhase.PREPARE_SOURCE)

        sdist_root = tmp_context.work_dir / "testpkg-1.0" / "testpkg-1.0"
        mock_env = Mock()
        item.bg_future = _make_resolved_future(
            PreparedSourceData(sdist_root_dir=sdist_root)
        )

        with (
            caplog.at_level(
                logging.INFO, logger="fromager.bootstrapper._prepare_source"
            ),
            patch.object(
                tmp_context.constraints,
                "get_constraint",
                return_value=Requirement("testpkg>=1.0"),
            ),
            patch(
                "fromager.build_environment.BuildEnvironment",
                return_value=mock_env,
            ),
            patch(
                "fromager.dependencies.get_build_system_dependencies",
                return_value=set(),
            ),
            patch.object(bt, "create_unresolved_work_items", return_value=[]),
        ):
            result = item.run(bt)

        assert isinstance(result[0], PrepareBuild)
        assert "matches constraint" in caplog.text


class TestPhasePrepareBuild:
    """Tests for PrepareBuild.run(): dep installation and extraction."""

    def test_installs_system_deps_and_returns_backend_sdist_items(
        self, tmp_context: WorkContext
    ) -> None:
        """Installs build system deps, extracts backend/sdist deps, returns all."""
        bt = bootstrapper.Bootstrapper(tmp_context)
        mock_env = Mock()
        sdist_root = tmp_context.work_dir / "testpkg-1.0" / "testpkg-1.0"
        system_deps = {Requirement("setuptools")}
        item = _make_build_item(
            phase=BootstrapPhase.PREPARE_BUILD,
            build_env=mock_env,
            sdist_root_dir=sdist_root,
            build_system_deps=system_deps,
        )
        wi = item.work_item

        backend_item = _make_resolve_item(req="wheel")
        sdist_item = _make_resolve_item(req="flit-core")

        with (
            patch(
                "fromager.dependencies.get_build_backend_dependencies",
                return_value={Requirement("wheel")},
            ),
            patch(
                "fromager.dependencies.get_build_sdist_dependencies",
                return_value={Requirement("flit-core")},
            ),
            patch.object(
                bt,
                "create_unresolved_work_items",
                side_effect=[[backend_item], [sdist_item]],
            ),
        ):
            result = item.run(bt)

        assert isinstance(result[0], Build)
        assert result[0].work_item is wi
        assert wi.build_backend_deps == {Requirement("wheel")}
        assert wi.build_sdist_deps == {Requirement("flit-core")}
        mock_env.install.assert_called_once_with(system_deps)
        assert result == [result[0], backend_item, sdist_item]

    def test_no_extra_deps_returns_item_only(self, tmp_context: WorkContext) -> None:
        """When backend and sdist deps are empty, returns only the item."""
        bt = bootstrapper.Bootstrapper(tmp_context)
        mock_env = Mock()
        sdist_root = tmp_context.work_dir / "testpkg-1.0" / "testpkg-1.0"
        system_deps = {Requirement("setuptools")}
        item = _make_build_item(
            phase=BootstrapPhase.PREPARE_BUILD,
            build_env=mock_env,
            sdist_root_dir=sdist_root,
            build_system_deps=system_deps,
        )

        with (
            patch(
                "fromager.dependencies.get_build_backend_dependencies",
                return_value=set(),
            ),
            patch(
                "fromager.dependencies.get_build_sdist_dependencies",
                return_value=set(),
            ),
            patch.object(
                bt,
                "create_unresolved_work_items",
                side_effect=[[], []],
            ),
        ):
            result = item.run(bt)

        assert len(result) == 1
        assert isinstance(result[0], Build)
        mock_env.install.assert_called_once_with(system_deps)

    def test_install_called_once_with_system_deps(
        self, tmp_context: WorkContext
    ) -> None:
        """build_env.install is called exactly once with build_system_deps."""
        bt = bootstrapper.Bootstrapper(tmp_context)
        mock_env = Mock()
        sdist_root = tmp_context.work_dir / "testpkg-1.0" / "testpkg-1.0"
        system_deps = {Requirement("setuptools"), Requirement("wheel")}
        item = _make_build_item(
            phase=BootstrapPhase.PREPARE_BUILD,
            build_env=mock_env,
            sdist_root_dir=sdist_root,
            build_system_deps=system_deps,
        )

        with (
            patch(
                "fromager.dependencies.get_build_backend_dependencies",
                return_value={Requirement("cython")},
            ),
            patch(
                "fromager.dependencies.get_build_sdist_dependencies",
                return_value=set(),
            ),
            patch.object(
                bt,
                "create_unresolved_work_items",
                side_effect=[[], []],
            ),
        ):
            item.run(bt)

        mock_env.install.assert_called_once_with(system_deps)

    def test_creates_items_with_correct_requirement_types(
        self, tmp_context: WorkContext
    ) -> None:
        """Backend deps tagged BUILD_BACKEND, sdist deps tagged BUILD_SDIST."""
        bt = bootstrapper.Bootstrapper(tmp_context)
        mock_env = Mock()
        sdist_root = tmp_context.work_dir / "testpkg-1.0" / "testpkg-1.0"
        item = _make_build_item(
            phase=BootstrapPhase.PREPARE_BUILD,
            build_env=mock_env,
            sdist_root_dir=sdist_root,
            build_system_deps={Requirement("setuptools")},
        )
        wi = item.work_item

        with (
            patch(
                "fromager.dependencies.get_build_backend_dependencies",
                return_value={Requirement("wheel")},
            ),
            patch(
                "fromager.dependencies.get_build_sdist_dependencies",
                return_value={Requirement("flit-core")},
            ),
            patch.object(
                bt,
                "create_unresolved_work_items",
                side_effect=[[], []],
            ) as mock_create_items,
        ):
            item.run(bt)

        calls = mock_create_items.call_args_list
        assert calls[0] == call(
            {Requirement("wheel")},
            RequirementType.BUILD_BACKEND,
            wi.req,
            wi.resolved_version,
        )
        assert calls[1] == call(
            {Requirement("flit-core")},
            RequirementType.BUILD_SDIST,
            wi.req,
            wi.resolved_version,
        )


class TestPhaseBuild:
    """Tests for Build.run(): conditional dep install and result construction."""

    def _make_build_phase_item(self, tmp_context: WorkContext) -> Build:
        mock_env = Mock()
        sdist_root = tmp_context.work_dir / "testpkg-1.0" / "testpkg-1.0"
        sdist_root.parent.mkdir(parents=True, exist_ok=True)
        item = _make_build_item(
            phase=BootstrapPhase.BUILD,
            build_env=mock_env,
            sdist_root_dir=sdist_root,
            build_system_deps={Requirement("setuptools")},
            build_backend_deps={Requirement("wheel")},
            build_sdist_deps={Requirement("flit-core")},
        )
        assert isinstance(item, Build)
        return item

    def test_disjoint_deps_installs_remaining(self, tmp_context: WorkContext) -> None:
        """Disjoint backend/sdist deps from system deps triggers install."""
        bt = bootstrapper.Bootstrapper(tmp_context)
        mock_env = Mock()
        sdist_root = tmp_context.work_dir / "testpkg-1.0" / "testpkg-1.0"
        sdist_root.parent.mkdir(parents=True, exist_ok=True)
        item = _make_build_item(
            phase=BootstrapPhase.BUILD,
            build_env=mock_env,
            sdist_root_dir=sdist_root,
            build_system_deps={Requirement("setuptools")},
            build_backend_deps={Requirement("wheel")},
            build_sdist_deps={Requirement("flit-core")},
        )
        mock_wheel = tmp_context.work_dir / "testpkg-1.0-py3-none-any.whl"

        with (
            patch.object(item, "do_build", return_value=(mock_wheel, None)),
            patch("fromager.sources.get_source_type", return_value=SourceType.SDIST),
        ):
            result = item.run(bt)

        mock_env.install.assert_called_once_with(
            {Requirement("wheel"), Requirement("flit-core")}
        )
        assert len(result) == 1
        assert isinstance(result[0], ProcessInstallDeps)

    def test_overlapping_deps_skips_install(self, tmp_context: WorkContext) -> None:
        """Overlapping backend/sdist deps with system deps skips install."""
        bt = bootstrapper.Bootstrapper(tmp_context)
        mock_env = Mock()
        sdist_root = tmp_context.work_dir / "testpkg-1.0" / "testpkg-1.0"
        sdist_root.parent.mkdir(parents=True, exist_ok=True)
        item = _make_build_item(
            phase=BootstrapPhase.BUILD,
            build_env=mock_env,
            sdist_root_dir=sdist_root,
            build_system_deps={Requirement("setuptools")},
            build_backend_deps={Requirement("setuptools")},
            build_sdist_deps=set(),
        )

        with (
            patch.object(item, "do_build", return_value=(None, None)),
            patch("fromager.sources.get_source_type", return_value=SourceType.SDIST),
        ):
            item.run(bt)

        mock_env.install.assert_not_called()

    def test_partial_overlap_deps_skips_install(self, tmp_context: WorkContext) -> None:
        """isdisjoint is False on partial overlap, so install is skipped entirely."""
        bt = bootstrapper.Bootstrapper(tmp_context)
        mock_env = Mock()
        sdist_root = tmp_context.work_dir / "testpkg-1.0" / "testpkg-1.0"
        sdist_root.parent.mkdir(parents=True, exist_ok=True)
        item = _make_build_item(
            phase=BootstrapPhase.BUILD,
            build_env=mock_env,
            sdist_root_dir=sdist_root,
            build_system_deps={Requirement("setuptools")},
            build_backend_deps={Requirement("setuptools"), Requirement("cython")},
            build_sdist_deps=set(),
        )

        with (
            patch.object(item, "do_build", return_value=(None, None)),
            patch("fromager.sources.get_source_type", return_value=SourceType.SDIST),
        ):
            item.run(bt)

        mock_env.install.assert_not_called()

    def test_do_build_receives_item_fields(self, tmp_context: WorkContext) -> None:
        """build_sdist_only and cached_wheel_filename are read directly by do_build, not forwarded as parameters."""
        bt = bootstrapper.Bootstrapper(tmp_context)
        mock_env = Mock()
        sdist_root = tmp_context.work_dir / "testpkg-1.0" / "testpkg-1.0"
        sdist_root.parent.mkdir(parents=True, exist_ok=True)
        cached_wheel = tmp_context.work_dir / "cached.whl"
        item = _make_build_item(
            phase=BootstrapPhase.BUILD,
            build_env=mock_env,
            sdist_root_dir=sdist_root,
            build_sdist_only=True,
            cached_wheel_filename=cached_wheel,
        )

        with (
            patch.object(item, "do_build", return_value=(None, None)) as mock_do_build,
            patch("fromager.sources.get_source_type", return_value=SourceType.SDIST),
        ):
            item.run(bt)

        mock_do_build.assert_called_once_with(bt.ctx, bt.explain)

    def test_build_result_references_item_build_env(
        self, tmp_context: WorkContext
    ) -> None:
        """build_result.build_env is the same object as item.work_item.build_env."""
        bt = bootstrapper.Bootstrapper(tmp_context)
        item = self._make_build_phase_item(tmp_context)
        wi = item.work_item

        with (
            patch.object(item, "do_build", return_value=(None, None)),
            patch("fromager.sources.get_source_type", return_value=SourceType.SDIST),
        ):
            item.run(bt)

        assert wi.build_result is not None
        assert wi.build_result.build_env is wi.build_env

    def test_build_result_uses_source_type_from_sources(
        self, tmp_context: WorkContext
    ) -> None:
        """source_type comes from sources.get_source_type, not hardcoded."""
        bt = bootstrapper.Bootstrapper(tmp_context)
        item = self._make_build_phase_item(tmp_context)
        wi = item.work_item

        with (
            patch.object(item, "do_build", return_value=(None, None)),
            patch("fromager.sources.get_source_type", return_value=SourceType.PREBUILT),
        ):
            item.run(bt)

        assert wi.build_result is not None
        assert wi.build_result.source_type == SourceType.PREBUILT

    def test_returns_single_process_install_deps_item(
        self, tmp_context: WorkContext
    ) -> None:
        """Build.run() returns exactly [ProcessInstallDeps]."""
        bt = bootstrapper.Bootstrapper(tmp_context)
        item = self._make_build_phase_item(tmp_context)

        with (
            patch.object(item, "do_build", return_value=(None, None)),
            patch("fromager.sources.get_source_type", return_value=SourceType.SDIST),
        ):
            result = item.run(bt)

        assert len(result) == 1
        assert isinstance(result[0], ProcessInstallDeps)
        assert result[0].work_item is item.work_item

    def test_phase_advancement_preserves_work_item_identity(
        self, tmp_context: WorkContext
    ) -> None:
        """When Build.run() returns ProcessInstallDeps, work_item is same obj."""
        bt = bootstrapper.Bootstrapper(tmp_context)
        item = self._make_build_phase_item(tmp_context)
        wi = item.work_item

        with (
            patch.object(item, "do_build", return_value=(None, None)),
            patch("fromager.sources.get_source_type", return_value=SourceType.SDIST),
        ):
            result = item.run(bt)

        assert result[0].work_item is wi


class TestPhaseProcessInstallDeps:
    """Tests for ProcessInstallDeps.run(): hooks, dep extraction, error modes."""

    def _make_process_item(self, tmp_context: WorkContext) -> ProcessInstallDeps:
        build_result = SourceBuildResult(
            wheel_filename=tmp_context.work_dir / "testpkg-1.0-py3-none-any.whl",
            sdist_filename=tmp_context.work_dir / "testpkg-1.0.tar.gz",
            unpack_dir=tmp_context.work_dir / "testpkg-1.0",
            sdist_root_dir=tmp_context.work_dir / "testpkg-1.0" / "testpkg-1.0",
            build_env=Mock(),
            source_type=SourceType.SDIST,
        )
        item = _make_build_item(
            phase=BootstrapPhase.PROCESS_INSTALL_DEPS,
            build_result=build_result,
            source_url="https://pkg.test/testpkg-1.0.tar.gz",
        )
        assert isinstance(item, ProcessInstallDeps)
        return item

    def test_normal_path_returns_item_and_dep_items(
        self, tmp_context: WorkContext
    ) -> None:
        """Normal path: hooks, deps, build order, returns [Complete, *dep_items]."""
        bt = bootstrapper.Bootstrapper(tmp_context)
        item = self._make_process_item(tmp_context)
        wi = item.work_item
        dep_item = _make_resolve_item(req="dep-a")

        with (
            patch("fromager.hooks.run_post_bootstrap_hooks"),
            patch(
                "fromager.bootstrapper._process_install_deps._get_install_dependencies",
                return_value=[Requirement("dep-a")],
            ),
            patch.object(
                tmp_context,
                "package_build_info",
                return_value=Mock(pre_built=False),
            ),
            patch.object(tmp_context.constraints, "get_constraint", return_value=None),
            patch.object(bt, "add_to_build_order") as mock_build_order,
            patch.object(
                bt, "create_unresolved_work_items", return_value=[dep_item]
            ) as mock_create_items,
        ):
            result = item.run(bt)

        assert isinstance(result[0], Complete)
        assert result[0].work_item is wi
        assert result[1] is dep_item
        mock_build_order.assert_called_once()
        mock_create_items.assert_called_once_with(
            [Requirement("dep-a")],
            RequirementType.INSTALL,
            wi.req,
            wi.resolved_version,
        )

    def test_hook_error_test_mode_records_and_continues(
        self, tmp_context: WorkContext
    ) -> None:
        """Hook error in test mode records failure, dep extraction still runs."""
        bt = bootstrapper.Bootstrapper(tmp_context, test_mode=True)
        item = self._make_process_item(tmp_context)

        with (
            patch(
                "fromager.hooks.run_post_bootstrap_hooks",
                side_effect=RuntimeError("hook failed"),
            ),
            patch(
                "fromager.bootstrapper._process_install_deps._get_install_dependencies",
                return_value=[],
            ) as mock_get_deps,
            patch.object(
                tmp_context,
                "package_build_info",
                return_value=Mock(pre_built=False),
            ),
            patch.object(tmp_context.constraints, "get_constraint", return_value=None),
            patch.object(bt, "add_to_build_order") as mock_build_order,
            patch.object(bt, "create_unresolved_work_items", return_value=[]),
        ):
            result = item.run(bt)

        assert isinstance(result[0], Complete)
        assert len(bt.failed_packages) == 1
        assert bt.failed_packages[0]["failure_type"] == "hook"
        mock_get_deps.assert_called_once()
        mock_build_order.assert_called_once()

    def test_hook_error_normal_mode_raises(self, tmp_context: WorkContext) -> None:
        """Hook error in normal mode propagates the exception."""
        bt = bootstrapper.Bootstrapper(tmp_context)
        item = self._make_process_item(tmp_context)

        with (
            patch(
                "fromager.hooks.run_post_bootstrap_hooks",
                side_effect=RuntimeError("hook failed"),
            ),
        ):
            with pytest.raises(RuntimeError, match="hook failed"):
                item.run(bt)

    def test_dep_extraction_error_test_mode_uses_empty_deps(
        self, tmp_context: WorkContext
    ) -> None:
        """Dep extraction error in test mode uses empty dep list, still writes build order."""
        bt = bootstrapper.Bootstrapper(tmp_context, test_mode=True)
        item = self._make_process_item(tmp_context)
        wi = item.work_item

        with (
            patch("fromager.hooks.run_post_bootstrap_hooks"),
            patch(
                "fromager.bootstrapper._process_install_deps._get_install_dependencies",
                side_effect=RuntimeError("dep failed"),
            ),
            patch.object(
                tmp_context,
                "package_build_info",
                return_value=Mock(pre_built=False),
            ),
            patch.object(tmp_context.constraints, "get_constraint", return_value=None),
            patch.object(bt, "add_to_build_order") as mock_build_order,
            patch.object(
                bt, "create_unresolved_work_items", return_value=[]
            ) as mock_create_items,
        ):
            result = item.run(bt)

        assert isinstance(result[0], Complete)
        assert len(bt.failed_packages) == 1
        assert bt.failed_packages[0]["failure_type"] == "dependency_extraction"
        mock_build_order.assert_called_once()
        mock_create_items.assert_called_once_with(
            [],
            RequirementType.INSTALL,
            wi.req,
            wi.resolved_version,
        )

    def test_dep_extraction_error_normal_mode_raises(
        self, tmp_context: WorkContext
    ) -> None:
        """Dep extraction error in normal mode propagates the exception."""
        bt = bootstrapper.Bootstrapper(tmp_context)
        item = self._make_process_item(tmp_context)

        with (
            patch("fromager.hooks.run_post_bootstrap_hooks"),
            patch(
                "fromager.bootstrapper._process_install_deps._get_install_dependencies",
                side_effect=RuntimeError("dep failed"),
            ),
        ):
            with pytest.raises(RuntimeError, match="dep failed"):
                item.run(bt)

    def test_no_install_deps_returns_item_only(self, tmp_context: WorkContext) -> None:
        """When no install deps, returns [Complete]."""
        bt = bootstrapper.Bootstrapper(tmp_context)
        item = self._make_process_item(tmp_context)

        with (
            patch("fromager.hooks.run_post_bootstrap_hooks"),
            patch(
                "fromager.bootstrapper._process_install_deps._get_install_dependencies",
                return_value=[],
            ),
            patch.object(
                tmp_context,
                "package_build_info",
                return_value=Mock(pre_built=False),
            ),
            patch.object(tmp_context.constraints, "get_constraint", return_value=None),
            patch.object(bt, "add_to_build_order"),
            patch.object(bt, "create_unresolved_work_items", return_value=[]),
        ):
            result = item.run(bt)

        assert len(result) == 1
        assert isinstance(result[0], Complete)

    def test_build_order_called_with_correct_args(
        self, tmp_context: WorkContext
    ) -> None:
        """add_to_build_order receives correct source_type, prebuilt, constraint."""
        bt = bootstrapper.Bootstrapper(tmp_context)
        item = self._make_process_item(tmp_context)
        wi = item.work_item
        constraint = Requirement("testpkg>=1.0")

        with (
            patch("fromager.hooks.run_post_bootstrap_hooks"),
            patch(
                "fromager.bootstrapper._process_install_deps._get_install_dependencies",
                return_value=[],
            ),
            patch.object(
                tmp_context,
                "package_build_info",
                return_value=Mock(pre_built=True),
            ),
            patch.object(
                tmp_context.constraints,
                "get_constraint",
                return_value=constraint,
            ),
            patch.object(bt, "add_to_build_order") as mock_build_order,
            patch.object(bt, "create_unresolved_work_items", return_value=[]),
        ):
            item.run(bt)

        mock_build_order.assert_called_once_with(
            req=wi.req,
            version=wi.resolved_version,
            source_url=wi.source_url,
            source_type=SourceType.SDIST,
            prebuilt=True,
            constraint=constraint,
        )


class TestFilterDepsSatisfiedByBuildSystem:
    """Tests for build-backend/sdist dep filtering against build-system deps."""

    def _setup_graph_with_build_system_dep(
        self,
        ctx: WorkContext,
        parent_name: str,
        parent_version: str,
        dep_name: str,
        dep_version: str,
        download_url: str = "https://pypi.test/simple/",
    ) -> None:
        """Add a parent node and a BUILD_SYSTEM edge to the dependency graph."""
        ctx.dependency_graph.add_dependency(
            parent_name=None,
            parent_version=None,
            req_type=RequirementType.TOP_LEVEL,
            req=Requirement(f"{parent_name}=={parent_version}"),
            req_version=Version(parent_version),
            download_url=download_url,
        )
        ctx.dependency_graph.add_dependency(
            parent_name=canonicalize_name(parent_name),
            parent_version=Version(parent_version),
            req_type=RequirementType.BUILD_SYSTEM,
            req=Requirement(f"{dep_name}=={dep_version}"),
            req_version=Version(dep_version),
            download_url=download_url,
        )

    def test_satisfied_dep_reuses_build_system_version(
        self, tmp_context: WorkContext
    ) -> None:
        """A build-backend dep with no pin reuses the build-system version."""
        self._setup_graph_with_build_system_dep(
            tmp_context, "biotite", "1.6.0", "hatch-cython", "0.5.0"
        )
        bt = bootstrapper.Bootstrapper(tmp_context)
        resolved_build_sys = {
            canonicalize_name("hatch-cython"): (
                Version("0.5.0"),
                "https://pypi.test/simple/",
            )
        }
        parent = (Requirement("biotite==1.6.0"), Version("1.6.0"))

        with patch.object(bt, "add_to_graph") as mock_add:
            result = bt.filter_deps_satisfied_by_build_system(
                {Requirement("hatch-cython")},
                resolved_build_sys,
                RequirementType.BUILD_BACKEND,
                parent,
            )

        assert result == set()
        mock_add.assert_called_once_with(
            req=Requirement("hatch-cython"),
            req_type=RequirementType.BUILD_BACKEND,
            req_version=Version("0.5.0"),
            download_url="https://pypi.test/simple/",
            parent=parent,
        )

    def test_satisfied_dep_with_compatible_specifier(
        self, tmp_context: WorkContext
    ) -> None:
        """A build-backend dep with a compatible specifier reuses build-system version."""
        bt = bootstrapper.Bootstrapper(tmp_context)
        resolved_build_sys = {
            canonicalize_name("foo"): (Version("1.5.0"), "https://pypi.test/simple/")
        }
        parent = (Requirement("testpkg==1.0"), Version("1.0"))

        with patch.object(bt, "add_to_graph") as mock_add:
            result = bt.filter_deps_satisfied_by_build_system(
                {Requirement("foo>=1.0")},
                resolved_build_sys,
                RequirementType.BUILD_BACKEND,
                parent,
            )

        assert result == set()
        mock_add.assert_called_once()

    def test_unsatisfied_dep_passes_through(self, tmp_context: WorkContext) -> None:
        """A dep not in build-system is returned for independent resolution."""
        bt = bootstrapper.Bootstrapper(tmp_context)
        resolved_build_sys = {
            canonicalize_name("foo"): (Version("1.0"), "https://pypi.test/simple/")
        }
        parent = (Requirement("testpkg==1.0"), Version("1.0"))
        wheel_req = Requirement("wheel")

        with patch.object(bt, "add_to_graph") as mock_add:
            result = bt.filter_deps_satisfied_by_build_system(
                {wheel_req},
                resolved_build_sys,
                RequirementType.BUILD_BACKEND,
                parent,
            )

        assert result == {wheel_req}
        mock_add.assert_not_called()

    def test_incompatible_specifier_passes_through(
        self, tmp_context: WorkContext
    ) -> None:
        """A dep whose specifier conflicts with build-system version is not filtered."""
        bt = bootstrapper.Bootstrapper(tmp_context)
        resolved_build_sys = {
            canonicalize_name("foo"): (Version("1.0"), "https://pypi.test/simple/")
        }
        parent = (Requirement("testpkg==1.0"), Version("1.0"))
        foo_req = Requirement("foo>=2.0")

        with patch.object(bt, "add_to_graph") as mock_add:
            result = bt.filter_deps_satisfied_by_build_system(
                {foo_req},
                resolved_build_sys,
                RequirementType.BUILD_BACKEND,
                parent,
            )

        assert result == {foo_req}
        mock_add.assert_not_called()

    def test_incompatible_specifier_logs_warning(
        self, tmp_context: WorkContext, caplog: pytest.LogCaptureFixture
    ) -> None:
        """A conflicting dep logs a warning about the build config conflict."""
        bt = bootstrapper.Bootstrapper(tmp_context)
        resolved_build_sys = {
            canonicalize_name("foo"): (Version("1.0"), "https://pypi.test/simple/")
        }
        parent = (Requirement("testpkg==1.0"), Version("1.0"))

        with patch.object(bt, "add_to_graph"):
            bt.filter_deps_satisfied_by_build_system(
                {Requirement("foo>=2.0")},
                resolved_build_sys,
                RequirementType.BUILD_BACKEND,
                parent,
            )

        assert "conflicts with" in caplog.text
        assert "foo>=2.0" in caplog.text
        assert "foo==1.0" in caplog.text

    def test_mixed_satisfied_and_unsatisfied(self, tmp_context: WorkContext) -> None:
        """Only unsatisfied deps are returned; satisfied deps get graph edges."""
        bt = bootstrapper.Bootstrapper(tmp_context)
        resolved_build_sys = {
            canonicalize_name("hatch-cython"): (
                Version("0.5.0"),
                "https://pypi.test/simple/",
            )
        }
        parent = (Requirement("biotite==1.6.0"), Version("1.6.0"))
        cython_req = Requirement("hatch-cython")
        wheel_req = Requirement("wheel")

        with patch.object(bt, "add_to_graph") as mock_add:
            result = bt.filter_deps_satisfied_by_build_system(
                {cython_req, wheel_req},
                resolved_build_sys,
                RequirementType.BUILD_BACKEND,
                parent,
            )

        assert result == {wheel_req}
        mock_add.assert_called_once()

    def test_empty_deps_returns_empty(self, tmp_context: WorkContext) -> None:
        """Empty deps set returns empty set."""
        bt = bootstrapper.Bootstrapper(tmp_context)
        resolved_build_sys = {
            canonicalize_name("foo"): (Version("1.0"), "https://pypi.test/simple/")
        }
        parent = (Requirement("testpkg==1.0"), Version("1.0"))

        result = bt.filter_deps_satisfied_by_build_system(
            set(),
            resolved_build_sys,
            RequirementType.BUILD_BACKEND,
            parent,
        )

        assert result == set()

    def test_empty_build_system_returns_all_deps(
        self, tmp_context: WorkContext
    ) -> None:
        """When no build-system deps exist, all deps pass through."""
        bt = bootstrapper.Bootstrapper(tmp_context)
        wheel_req = Requirement("wheel")
        parent = (Requirement("testpkg==1.0"), Version("1.0"))

        result = bt.filter_deps_satisfied_by_build_system(
            {wheel_req},
            {},
            RequirementType.BUILD_BACKEND,
            parent,
        )

        assert result == {wheel_req}

    def test_dep_with_extras_passes_through(self, tmp_context: WorkContext) -> None:
        """A dep with extras is not filtered even if the name matches."""
        bt = bootstrapper.Bootstrapper(tmp_context)
        resolved_build_sys = {
            canonicalize_name("foo"): (Version("1.0"), "https://pypi.test/simple/")
        }
        parent = (Requirement("testpkg==1.0"), Version("1.0"))
        extras_req = Requirement("foo[bar]>=1.0")

        with patch.object(bt, "add_to_graph") as mock_add:
            result = bt.filter_deps_satisfied_by_build_system(
                {extras_req},
                resolved_build_sys,
                RequirementType.BUILD_BACKEND,
                parent,
            )

        assert result == {extras_req}
        mock_add.assert_not_called()


class TestGetResolvedBuildSystemVersions:
    """Tests for get_resolved_build_system_versions."""

    def test_returns_build_system_edges(self, tmp_context: WorkContext) -> None:
        """Returns resolved versions from BUILD_SYSTEM edges."""
        tmp_context.dependency_graph.add_dependency(
            parent_name=None,
            parent_version=None,
            req_type=RequirementType.TOP_LEVEL,
            req=Requirement("biotite==1.6.0"),
            req_version=Version("1.6.0"),
            download_url="https://pypi.test/simple/",
        )
        tmp_context.dependency_graph.add_dependency(
            parent_name=canonicalize_name("biotite"),
            parent_version=Version("1.6.0"),
            req_type=RequirementType.BUILD_SYSTEM,
            req=Requirement("hatch-cython==0.5"),
            req_version=Version("0.5.0"),
            download_url="https://pypi.test/hatch-cython/",
        )
        tmp_context.dependency_graph.add_dependency(
            parent_name=canonicalize_name("biotite"),
            parent_version=Version("1.6.0"),
            req_type=RequirementType.INSTALL,
            req=Requirement("numpy"),
            req_version=Version("2.0.0"),
            download_url="https://pypi.test/numpy/",
        )

        bt = bootstrapper.Bootstrapper(tmp_context)
        wi = _make_work_item(req="biotite", version="1.6.0")

        result = bt.get_resolved_build_system_versions(wi)

        assert canonicalize_name("hatch-cython") in result
        assert result[canonicalize_name("hatch-cython")] == (
            Version("0.5.0"),
            "https://pypi.test/hatch-cython/",
        )
        assert canonicalize_name("numpy") not in result

    def test_returns_empty_when_parent_not_in_graph(
        self, tmp_context: WorkContext
    ) -> None:
        """Returns empty dict when parent node is not in the graph."""
        bt = bootstrapper.Bootstrapper(tmp_context)
        wi = _make_work_item(req="nonexistent", version="1.0")

        result = bt.get_resolved_build_system_versions(wi)

        assert result == {}


class TestPhasePrepareBuildFiltering:
    """Tests for PrepareBuild.run() with build-system satisfaction filtering."""

    def test_satisfied_backend_dep_skips_resolve(
        self, tmp_context: WorkContext
    ) -> None:
        """Backend dep satisfied by build-system is not sent to RESOLVE."""
        tmp_context.dependency_graph.add_dependency(
            parent_name=None,
            parent_version=None,
            req_type=RequirementType.TOP_LEVEL,
            req=Requirement("biotite==1.6.0"),
            req_version=Version("1.6.0"),
            download_url="https://pypi.test/simple/",
        )
        tmp_context.dependency_graph.add_dependency(
            parent_name=canonicalize_name("biotite"),
            parent_version=Version("1.6.0"),
            req_type=RequirementType.BUILD_SYSTEM,
            req=Requirement("hatch-cython==0.5"),
            req_version=Version("0.5.0"),
            download_url="https://pypi.test/simple/",
        )

        bt = bootstrapper.Bootstrapper(tmp_context)
        mock_env = Mock()
        sdist_root = tmp_context.work_dir / "biotite-1.6.0" / "biotite-1.6.0"
        item = _make_build_item(
            req="biotite",
            version="1.6.0",
            phase=BootstrapPhase.PREPARE_BUILD,
            build_env=mock_env,
            sdist_root_dir=sdist_root,
            build_system_deps={Requirement("hatch-cython==0.5")},
        )
        wi = item.work_item

        with (
            patch(
                "fromager.dependencies.get_build_backend_dependencies",
                return_value={Requirement("hatch-cython")},
            ),
            patch(
                "fromager.dependencies.get_build_sdist_dependencies",
                return_value=set(),
            ),
            patch.object(
                bt,
                "create_unresolved_work_items",
                return_value=[],
            ) as mock_create,
        ):
            result = item.run(bt)

        assert isinstance(result[0], Build)
        calls = mock_create.call_args_list
        assert calls[0][0][0] == set()
        assert calls[1][0][0] == set()
        assert wi.build_backend_deps == set()
        assert len(result) == 1

    def test_extras_dep_not_filtered(self, tmp_context: WorkContext) -> None:
        """Backend dep with extras passes through even if name matches."""
        tmp_context.dependency_graph.add_dependency(
            parent_name=None,
            parent_version=None,
            req_type=RequirementType.TOP_LEVEL,
            req=Requirement("testpkg==1.0"),
            req_version=Version("1.0"),
            download_url="https://pypi.test/simple/",
        )
        tmp_context.dependency_graph.add_dependency(
            parent_name=canonicalize_name("testpkg"),
            parent_version=Version("1.0"),
            req_type=RequirementType.BUILD_SYSTEM,
            req=Requirement("foo==1.0"),
            req_version=Version("1.0"),
            download_url="https://pypi.test/simple/",
        )

        bt = bootstrapper.Bootstrapper(tmp_context)
        mock_env = Mock()
        sdist_root = tmp_context.work_dir / "testpkg-1.0" / "testpkg-1.0"
        extras_req = Requirement("foo[bar]>=1.0")
        item = _make_build_item(
            phase=BootstrapPhase.PREPARE_BUILD,
            build_env=mock_env,
            sdist_root_dir=sdist_root,
            build_system_deps={Requirement("foo==1.0")},
        )

        resolve_item = _make_resolve_item(req="foo")

        with (
            patch(
                "fromager.dependencies.get_build_backend_dependencies",
                return_value={extras_req},
            ),
            patch(
                "fromager.dependencies.get_build_sdist_dependencies",
                return_value=set(),
            ),
            patch.object(
                bt,
                "create_unresolved_work_items",
                side_effect=[[resolve_item], []],
            ) as mock_create,
        ):
            result = item.run(bt)

        calls = mock_create.call_args_list
        assert calls[0][0][0] == {extras_req}
        assert item.work_item.build_backend_deps == {extras_req}
        assert result[1] is resolve_item

    def test_unsatisfied_backend_dep_creates_resolve_item(
        self, tmp_context: WorkContext
    ) -> None:
        """Backend dep NOT in build-system is sent to RESOLVE normally."""
        tmp_context.dependency_graph.add_dependency(
            parent_name=None,
            parent_version=None,
            req_type=RequirementType.TOP_LEVEL,
            req=Requirement("testpkg==1.0"),
            req_version=Version("1.0"),
            download_url="https://pypi.test/simple/",
        )

        bt = bootstrapper.Bootstrapper(tmp_context)
        mock_env = Mock()
        sdist_root = tmp_context.work_dir / "testpkg-1.0" / "testpkg-1.0"
        item = _make_build_item(
            phase=BootstrapPhase.PREPARE_BUILD,
            build_env=mock_env,
            sdist_root_dir=sdist_root,
            build_system_deps={Requirement("setuptools")},
        )

        resolve_item = _make_resolve_item(req="wheel")

        with (
            patch(
                "fromager.dependencies.get_build_backend_dependencies",
                return_value={Requirement("wheel")},
            ),
            patch(
                "fromager.dependencies.get_build_sdist_dependencies",
                return_value=set(),
            ),
            patch.object(
                bt,
                "create_unresolved_work_items",
                side_effect=[[resolve_item], []],
            ) as mock_create,
        ):
            result = item.run(bt)

        calls = mock_create.call_args_list
        assert calls[0][0][0] == {Requirement("wheel")}
        assert result[1] is resolve_item


class TestBackgroundWork:
    """Tests for background_work() dispatch on Phase subclasses."""

    def test_resolve_item_background_work_returns_callable(
        self, tmp_context: WorkContext
    ) -> None:
        """Resolve.background_work(bt) returns a non-None callable."""
        bt = bootstrapper.Bootstrapper(tmp_context)
        item = _make_resolve_item()
        bg = item.background_work(bt)
        assert bg is not None
        assert callable(bg)

    def test_prepare_source_item_background_work_source(
        self, tmp_context: WorkContext
    ) -> None:
        """When pbi_pre_built=False, background_work() returns a source callable."""
        bt = bootstrapper.Bootstrapper(tmp_context)
        wi = _make_work_item(
            req="testpkg",
            version="1.0",
            source_url="https://pypi.test/testpkg-1.0.tar.gz",
        )
        wi.pbi_pre_built = False
        item = PrepareSource(wi)
        bg = item.background_work(bt)
        assert bg is not None
        assert callable(bg)

    def test_prepare_source_item_background_work_prebuilt(
        self, tmp_context: WorkContext
    ) -> None:
        """When pbi_pre_built=True, background_work() returns a prebuilt callable."""
        bt = bootstrapper.Bootstrapper(tmp_context)
        wi = _make_work_item(
            req="testpkg",
            version="1.0",
            source_url="https://pypi.test/testpkg-1.0-py3-none-any.whl",
        )
        wi.pbi_pre_built = True
        item = PrepareSource(wi)
        bg = item.background_work(bt)
        assert bg is not None
        assert callable(bg)


class TestAsJson:
    """Tests for Phase.as_json() serialization."""

    @pytest.mark.parametrize(
        "cls, expected_phase",
        [
            (Resolve, BootstrapPhase.RESOLVE),
            (Start, BootstrapPhase.START),
            (PrepareSource, BootstrapPhase.PREPARE_SOURCE),
            (PrepareBuild, BootstrapPhase.PREPARE_BUILD),
            (Build, BootstrapPhase.BUILD),
            (ProcessInstallDeps, BootstrapPhase.PROCESS_INSTALL_DEPS),
            (Complete, BootstrapPhase.COMPLETE),
        ],
    )
    def test_phase_field_per_subclass(
        self, cls: type[Phase], expected_phase: BootstrapPhase
    ) -> None:
        wi = _make_work_item(req="testpkg")
        item = cls(wi)
        data = item.as_json()
        assert data["phase"] == str(expected_phase)


class TestThreadPoolSubmission:
    """Tests that exercise the real ThreadPoolExecutor submission path."""

    def test_push_items_sets_bg_future_when_pool_exists(
        self, tmp_context: WorkContext
    ) -> None:
        """_push_items submits RESOLVE work to a real thread pool."""
        expected = [("https://pkg.test/testpkg-1.0.tar.gz", Version("1.0"))]

        with bootstrapper.Bootstrapper(tmp_context, num_bg_threads=1) as bt:
            with patch.object(bt._resolver, "resolve", return_value=expected):
                item = _make_resolve_item(req="testpkg")
                stack: list[Phase] = []

                bt._push_items(stack, [item])

                # bg_future must be set on the Phase, not None
                assert item.bg_future is not None
                assert isinstance(item.bg_future, concurrent.futures.Future)

                # Blocking on result() exercises the actual thread submission path
                result = item.bg_future.result(timeout=10)
                assert result == expected

                # Resolve.run() processes the future correctly
                new_items = item.run(bt)

            assert len(new_items) == 1
            assert isinstance(new_items[0], Start)
            assert new_items[0].work_item.resolved_version == Version("1.0")

    def test_push_items_no_bg_future_when_pool_is_none(
        self, tmp_context: WorkContext
    ) -> None:
        """When _bg_pool is None, calling _push_items leaves item.bg_future as None."""
        bt = bootstrapper.Bootstrapper(tmp_context)
        bt._bg_pool = None
        item = _make_resolve_item(req="testpkg")
        stack: list[Phase] = []

        bt._push_items(stack, [item])

        assert item.bg_future is None


class TestCreateUnresolvedWorkItemsReturnType:
    """create_unresolved_work_items returns Resolve instances."""

    def test_returns_resolve_items(self, tmp_context: WorkContext) -> None:
        bt = bootstrapper.Bootstrapper(tmp_context)
        deps = [Requirement("dep-a")]
        items = bt.create_unresolved_work_items(
            deps, RequirementType.INSTALL, Requirement("parent"), Version("1.0")
        )
        assert len(items) == 1
        assert isinstance(items[0], Resolve)
        assert items[0].work_item.req == Requirement("dep-a")
        assert items[0].work_item.req_type == RequirementType.INSTALL