Merge pull request #2 from grimlor/refactor/job-board-port-protocol

refactor(adapters): extract JobBoardPort Protocol from JobBoardAdapter ABC

Author: grimlor

src/jobsearch_rag/adapters/__init__.py

@@ -13,6 +13,7 @@
     ziprecruiter as _zr,  # noqa: F401  # pyright: ignore[reportUnusedImport]  # side-effect: triggers @register
 )
 from jobsearch_rag.adapters.base import JobBoardAdapter, JobListing
+from jobsearch_rag.adapters.ports import JobBoardPort
 from jobsearch_rag.adapters.registry import AdapterRegistry
 
-__all__ = ["AdapterRegistry", "JobBoardAdapter", "JobListing"]
+__all__ = ["AdapterRegistry", "JobBoardAdapter", "JobBoardPort", "JobListing"]

src/jobsearch_rag/adapters/ports.py

@@ -0,0 +1,52 @@
+"""Protocol defining the structural interface for job board adapters."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Protocol, runtime_checkable
+
+if TYPE_CHECKING:
+    from playwright.async_api import Page
+
+    from jobsearch_rag.adapters.base import JobListing
+
+
+@runtime_checkable
+class JobBoardPort(Protocol):
+    """
+    Structural interface for job board integration.
+
+    Callers depend on this Protocol rather than the concrete
+    ``JobBoardAdapter`` ABC.  Any object providing these members
+    satisfies the contract — inheritance is not required.
+    """
+
+    @property
+    def board_name(self) -> str:
+        """Unique identifier string for this board."""
+        ...
+
+    @property
+    def rate_limit_seconds(self) -> tuple[float, float]:
+        """(min, max) seconds to sleep between page loads."""
+        ...
+
+    async def authenticate(self, page: Page) -> None:
+        """Establish an authenticated session."""
+        ...
+
+    async def search(
+        self,
+        page: Page,
+        query: str,
+        max_pages: int,
+    ) -> list[JobListing]:
+        """Navigate search results and return shallow listings."""
+        ...
+
+    async def extract_detail(
+        self,
+        page: Page,
+        listing: JobListing,
+    ) -> JobListing:
+        """Navigate to listing URL and populate full_text."""
+        ...

src/jobsearch_rag/adapters/registry.py

@@ -2,12 +2,12 @@
 
 from __future__ import annotations
 
-from typing import TYPE_CHECKING, Any, ClassVar, TypeVar
+from typing import TYPE_CHECKING, Any, ClassVar, TypeVar, cast
 
 if TYPE_CHECKING:
-    from jobsearch_rag.adapters.base import JobBoardAdapter
+    from jobsearch_rag.adapters.ports import JobBoardPort
 
-_T = TypeVar("_T", bound="JobBoardAdapter")
+_T = TypeVar("_T", bound="JobBoardPort")
 
 
 class AdapterRegistry:
@@ -24,17 +24,17 @@ def board_name(self) -> str:
             ...
     """
 
-    _registry: ClassVar[dict[str, type[JobBoardAdapter]]] = {}
+    _registry: ClassVar[dict[str, type[JobBoardPort]]] = {}
 
     @classmethod
     def register(cls, adapter_class: type[_T]) -> type[_T]:
         """Class decorator — registers an adapter by its ``board_name``."""
         instance = adapter_class.__new__(adapter_class)
-        cls._registry[instance.board_name] = adapter_class  # type: ignore[assignment]  # _T is a subtype of JobBoardAdapter
+        cls._registry[instance.board_name] = cast("type[JobBoardPort]", adapter_class)
         return adapter_class
 
     @classmethod
-    def get(cls, board_name: str, **kwargs: Any) -> JobBoardAdapter:
+    def get(cls, board_name: str, **kwargs: Any) -> JobBoardPort:
         """
         Return a new instance of the adapter registered under *board_name*.
 

src/jobsearch_rag/adapters/session.py

@@ -43,7 +43,7 @@
 if TYPE_CHECKING:
     from playwright.async_api import Browser, BrowserContext, Page, Playwright
 
-    from jobsearch_rag.adapters.base import JobBoardAdapter
+    from jobsearch_rag.adapters.ports import JobBoardPort
 
 
 # ---------------------------------------------------------------------------
@@ -173,7 +173,7 @@ def _terminate_process(proc: subprocess.Popen[bytes]) -> None:
 
 
 async def throttle(
-    adapter: JobBoardAdapter,
+    adapter: JobBoardPort,
     rate_limit_range: tuple[float, float] | None = None,
 ) -> float:
     """

tests/conftest.py

@@ -50,9 +50,9 @@
 from tests.constants import EMBED_FAKE as EMBED_FAKE  # re-export for fixtures below
 
 if TYPE_CHECKING:
-    from collections.abc import Callable, Generator, Iterator
+    from collections.abc import Callable, Generator, Iterator, Mapping
 
-    from jobsearch_rag.adapters.base import JobBoardAdapter
+    from jobsearch_rag.adapters.ports import JobBoardPort
 
 _PROJECT_OUTPUT = Path(__file__).resolve().parent.parent / "output"
 
@@ -92,7 +92,7 @@ def __init__(self, *args: Any, **kwargs: Any) -> None:
 
 @contextmanager
 def adapter_override(
-    factories: dict[str, Callable[..., JobBoardAdapter]],
+    factories: Mapping[str, Callable[..., JobBoardPort]],
     *,
     clear: bool = False,
 ) -> Generator[None, None, None]:

tests/test_registry.py

@@ -23,6 +23,7 @@
 from jobsearch_rag.adapters.base import JobBoardAdapter, JobListing
 from jobsearch_rag.adapters.indeed import IndeedAdapter
 from jobsearch_rag.adapters.linkedin import LinkedInAdapter
+from jobsearch_rag.adapters.ports import JobBoardPort
 from jobsearch_rag.adapters.registry import AdapterRegistry
 from jobsearch_rag.adapters.weworkremotely import WeWorkRemotelyAdapter
 from tests.conftest import adapter_override
@@ -32,7 +33,7 @@
 # ---------------------------------------------------------------------------
 
 
-def _make_adapter_class(name: str) -> type[JobBoardAdapter]:
+def _make_adapter_class(name: str) -> type[JobBoardPort]:
     """Dynamically create a concrete adapter class for testing."""
 
     class _TestAdapter(JobBoardAdapter):
@@ -128,7 +129,7 @@ def test_registered_adapter_is_retrievable_by_board_name(self) -> None:
         adapter = AdapterRegistry.get("ziprecruiter")
 
         # Then: returns a working adapter instance
-        assert isinstance(adapter, JobBoardAdapter), "Should return a JobBoardAdapter instance"
+        assert isinstance(adapter, JobBoardPort), "Should return a JobBoardPort instance"
         assert adapter.board_name == "ziprecruiter", "Board name should match"
 
     def test_retrieving_unregistered_board_name_raises_value_error_with_name(self) -> None:
@@ -467,7 +468,7 @@ class TestStubAdapterContract:
         Never: Patch adapter internals
     """
 
-    _STUB_BOARDS: typing.ClassVar[list[tuple[str, type[JobBoardAdapter]]]] = [
+    _STUB_BOARDS: typing.ClassVar[list[tuple[str, type[JobBoardPort]]]] = [
         ("linkedin", LinkedInAdapter),
         ("indeed", IndeedAdapter),
         ("weworkremotely", WeWorkRemotelyAdapter),
@@ -479,7 +480,7 @@ class TestStubAdapterContract:
         ids=["linkedin", "indeed", "weworkremotely"],
     )
     def test_stub_adapter_reports_correct_board_name(
-        self, expected_name: str, adapter_cls: type[JobBoardAdapter]
+        self, expected_name: str, adapter_cls: type[JobBoardPort]
     ) -> None:
         """
         GIVEN a stub adapter instance
@@ -521,7 +522,7 @@ def test_linkedin_adapter_overrides_rate_limit_for_aggressive_detection(
     )
     @pytest.mark.xfail(reason="Adapter not yet implemented")
     def test_stub_authenticate_completes_on_valid_session(
-        self, _name: str, adapter_cls: type[JobBoardAdapter]
+        self, _name: str, adapter_cls: type[JobBoardPort]
     ) -> None:
         """
         GIVEN a valid browser session
@@ -542,7 +543,7 @@ def test_stub_authenticate_completes_on_valid_session(
     )
     @pytest.mark.xfail(reason="Adapter not yet implemented")
     def test_stub_search_returns_list_of_job_listings(
-        self, _name: str, adapter_cls: type[JobBoardAdapter]
+        self, _name: str, adapter_cls: type[JobBoardPort]
     ) -> None:
         """
         GIVEN a valid browser session
@@ -568,7 +569,7 @@ def test_stub_search_returns_list_of_job_listings(
     )
     @pytest.mark.xfail(reason="Adapter not yet implemented")
     def test_stub_extract_detail_populates_full_text(
-        self, _name: str, adapter_cls: type[JobBoardAdapter]
+        self, _name: str, adapter_cls: type[JobBoardPort]
     ) -> None:
         """
         GIVEN a shallow listing without full_text