julee 0.1.4__py3-none-any.whl → 0.1.6__py3-none-any.whl

julee/docs/sphinx_hcd/sphinx/adapters.py

@@ -0,0 +1,116 @@
+"""Sync adapters for async repositories.
+
+Sphinx directives are synchronous, but our domain repositories are async
+(following julee patterns). This module provides adapters to bridge the gap.
+"""
+
+import asyncio
+from typing import Any, Generic, TypeVar
+
+from pydantic import BaseModel
+
+from ..domain.repositories.base import BaseRepository
+
+T = TypeVar("T", bound=BaseModel)
+
+
+class SyncRepositoryAdapter(Generic[T]):
+    """Synchronous wrapper for async repository methods.
+
+    Provides a synchronous interface to async repositories for use in
+    Sphinx directives. Uses asyncio.run() to execute async methods.
+
+    Example:
+        >>> async_repo = MemoryStoryRepository()
+        >>> sync_repo = SyncRepositoryAdapter(async_repo)
+        >>> story = sync_repo.get("my-story-slug")  # Sync call
+
+    Note:
+        This adapter is designed for use in Sphinx's synchronous directive
+        system. The overhead of asyncio.run() is negligible for in-memory
+        repositories.
+    """
+
+    def __init__(self, async_repo: BaseRepository[T]) -> None:
+        """Initialize with an async repository.
+
+        Args:
+            async_repo: An async repository implementing BaseRepository[T]
+        """
+        self._repo = async_repo
+
+    @property
+    def async_repo(self) -> BaseRepository[T]:
+        """Access the underlying async repository."""
+        return self._repo
+
+    def get(self, entity_id: str) -> T | None:
+        """Retrieve an entity by ID (sync wrapper).
+
+        Args:
+            entity_id: Unique entity identifier
+
+        Returns:
+            Entity if found, None otherwise
+        """
+        return asyncio.run(self._repo.get(entity_id))
+
+    def get_many(self, entity_ids: list[str]) -> dict[str, T | None]:
+        """Retrieve multiple entities by ID (sync wrapper).
+
+        Args:
+            entity_ids: List of unique entity identifiers
+
+        Returns:
+            Dict mapping entity_id to entity (or None if not found)
+        """
+        return asyncio.run(self._repo.get_many(entity_ids))
+
+    def save(self, entity: T) -> None:
+        """Save an entity (sync wrapper).
+
+        Args:
+            entity: Complete entity to save
+        """
+        asyncio.run(self._repo.save(entity))
+
+    def list_all(self) -> list[T]:
+        """List all entities (sync wrapper).
+
+        Returns:
+            List of all entities in the repository
+        """
+        return asyncio.run(self._repo.list_all())
+
+    def delete(self, entity_id: str) -> bool:
+        """Delete an entity by ID (sync wrapper).
+
+        Args:
+            entity_id: Unique entity identifier
+
+        Returns:
+            True if entity was deleted, False if not found
+        """
+        return asyncio.run(self._repo.delete(entity_id))
+
+    def clear(self) -> None:
+        """Remove all entities from the repository (sync wrapper)."""
+        asyncio.run(self._repo.clear())
+
+    def run_async(self, coro: Any) -> Any:
+        """Run an arbitrary async method on the underlying repository.
+
+        Useful for repository-specific methods not in BaseRepository.
+
+        Args:
+            coro: A coroutine to execute
+
+        Returns:
+            The result of the coroutine
+
+        Example:
+            >>> result = sync_repo.run_async(
+            ...     sync_repo.async_repo.find_by_persona("Staff Member")
+            ... )
+        """
+        return asyncio.run(coro)

julee/docs/sphinx_hcd/sphinx/context.py

@@ -0,0 +1,163 @@
+"""HCDContext for unified repository access.
+
+Provides a single context object that holds all repositories for the
+HCD documentation system. This replaces the scattered global/env registries
+with a unified, type-safe interface.
+"""
+
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING
+
+from ..repositories.memory import (
+    MemoryAcceleratorRepository,
+    MemoryAppRepository,
+    MemoryCodeInfoRepository,
+    MemoryEpicRepository,
+    MemoryIntegrationRepository,
+    MemoryJourneyRepository,
+    MemoryStoryRepository,
+)
+from .adapters import SyncRepositoryAdapter
+
+if TYPE_CHECKING:
+    from ..domain.models import (
+        Accelerator,
+        App,
+        BoundedContextInfo,
+        Epic,
+        Integration,
+        Journey,
+        Story,
+    )
+
+
+@dataclass
+class HCDContext:
+    """Unified context for HCD documentation.
+
+    Holds all repositories needed for the HCD documentation system.
+    Each repository is wrapped in a SyncRepositoryAdapter for use in
+    Sphinx's synchronous directive system.
+
+    This context is created at builder-inited and attached to the
+    Sphinx app object. It can be retrieved using get_hcd_context().
+
+    Attributes:
+        story_repo: Repository for Story entities
+        journey_repo: Repository for Journey entities
+        epic_repo: Repository for Epic entities
+        app_repo: Repository for App entities
+        accelerator_repo: Repository for Accelerator entities
+        integration_repo: Repository for Integration entities
+        code_info_repo: Repository for BoundedContextInfo entities
+    """
+
+    story_repo: SyncRepositoryAdapter["Story"] = field(
+        default_factory=lambda: SyncRepositoryAdapter(MemoryStoryRepository())
+    )
+    journey_repo: SyncRepositoryAdapter["Journey"] = field(
+        default_factory=lambda: SyncRepositoryAdapter(MemoryJourneyRepository())
+    )
+    epic_repo: SyncRepositoryAdapter["Epic"] = field(
+        default_factory=lambda: SyncRepositoryAdapter(MemoryEpicRepository())
+    )
+    app_repo: SyncRepositoryAdapter["App"] = field(
+        default_factory=lambda: SyncRepositoryAdapter(MemoryAppRepository())
+    )
+    accelerator_repo: SyncRepositoryAdapter["Accelerator"] = field(
+        default_factory=lambda: SyncRepositoryAdapter(MemoryAcceleratorRepository())
+    )
+    integration_repo: SyncRepositoryAdapter["Integration"] = field(
+        default_factory=lambda: SyncRepositoryAdapter(MemoryIntegrationRepository())
+    )
+    code_info_repo: SyncRepositoryAdapter["BoundedContextInfo"] = field(
+        default_factory=lambda: SyncRepositoryAdapter(MemoryCodeInfoRepository())
+    )
+
+    def clear_all(self) -> None:
+        """Clear all repositories.
+
+        Useful for testing or when rebuilding documentation from scratch.
+        """
+        self.story_repo.clear()
+        self.journey_repo.clear()
+        self.epic_repo.clear()
+        self.app_repo.clear()
+        self.accelerator_repo.clear()
+        self.integration_repo.clear()
+        self.code_info_repo.clear()
+
+    def clear_by_docname(self, docname: str) -> dict[str, int]:
+        """Clear entities defined in a specific document.
+
+        Used during incremental builds when a document is re-read.
+        Only entities that track docname are cleared (journey, epic, accelerator).
+
+        Args:
+            docname: RST document name
+
+        Returns:
+            Dict mapping entity type to number of entities removed
+        """
+        results = {}
+
+        # Journey repo has clear_by_docname
+        journey_async = self.journey_repo.async_repo
+        results["journeys"] = self.journey_repo.run_async(
+            journey_async.clear_by_docname(docname)  # type: ignore
+        )
+
+        # Epic repo has clear_by_docname
+        epic_async = self.epic_repo.async_repo
+        results["epics"] = self.epic_repo.run_async(
+            epic_async.clear_by_docname(docname)  # type: ignore
+        )
+
+        # Accelerator repo has clear_by_docname
+        accel_async = self.accelerator_repo.async_repo
+        results["accelerators"] = self.accelerator_repo.run_async(
+            accel_async.clear_by_docname(docname)  # type: ignore
+        )
+
+        return results
+
+
+def get_hcd_context(app) -> HCDContext:
+    """Get the HCDContext from a Sphinx app.
+
+    Args:
+        app: Sphinx application object
+
+    Returns:
+        HCDContext attached to the app
+
+    Raises:
+        AttributeError: If context hasn't been initialized
+    """
+    return app._hcd_context
+
+
+def set_hcd_context(app, context: HCDContext) -> None:
+    """Set the HCDContext on a Sphinx app.
+
+    Args:
+        app: Sphinx application object
+        context: HCDContext to attach
+    """
+    app._hcd_context = context
+
+
+def ensure_hcd_context(app) -> HCDContext:
+    """Ensure the HCDContext exists on a Sphinx app.
+
+    Creates a new context if one doesn't exist.
+
+    Args:
+        app: Sphinx application object
+
+    Returns:
+        HCDContext attached to the app
+    """
+    if not hasattr(app, "_hcd_context"):
+        set_hcd_context(app, HCDContext())
+    return get_hcd_context(app)

julee/docs/sphinx_hcd/sphinx/directives/__init__.py

@@ -0,0 +1,160 @@
+"""Sphinx directives for sphinx_hcd.
+
+Thin directive adapters that use domain models and repositories.
+"""
+
+from .accelerator import (
+    AcceleratorDependencyDiagramDirective,
+    AcceleratorDependencyDiagramPlaceholder,
+    AcceleratorIndexDirective,
+    AcceleratorIndexPlaceholder,
+    AcceleratorsForAppDirective,
+    AcceleratorsForAppPlaceholder,
+    AcceleratorStatusDirective,
+    DefineAcceleratorDirective,
+    DefineAcceleratorPlaceholder,
+    DependentAcceleratorsDirective,
+    DependentAcceleratorsPlaceholder,
+    clear_accelerator_state,
+    process_accelerator_placeholders,
+)
+from .app import (
+    AppIndexDirective,
+    AppIndexPlaceholder,
+    AppsForPersonaDirective,
+    AppsForPersonaPlaceholder,
+    DefineAppDirective,
+    DefineAppPlaceholder,
+    process_app_placeholders,
+)
+from .base import HCDDirective, make_deprecated_directive
+from .epic import (
+    DefineEpicDirective,
+    EpicIndexDirective,
+    EpicIndexPlaceholder,
+    EpicsForPersonaDirective,
+    EpicsForPersonaPlaceholder,
+    EpicStoryDirective,
+    clear_epic_state,
+    process_epic_placeholders,
+)
+from .integration import (
+    DefineIntegrationDirective,
+    DefineIntegrationPlaceholder,
+    IntegrationIndexDirective,
+    IntegrationIndexPlaceholder,
+    process_integration_placeholders,
+)
+from .journey import (
+    DefineJourneyDirective,
+    JourneyDependencyGraphDirective,
+    JourneyDependencyGraphPlaceholder,
+    JourneyIndexDirective,
+    JourneysForPersonaDirective,
+    StepEpicDirective,
+    StepPhaseDirective,
+    StepStoryDirective,
+    clear_journey_state,
+    process_dependency_graph_placeholder,
+    process_journey_steps,
+)
+from .persona import (
+    PersonaDiagramDirective,
+    PersonaDiagramPlaceholder,
+    PersonaIndexDiagramDirective,
+    PersonaIndexDiagramPlaceholder,
+    process_persona_placeholders,
+)
+from .story import (
+    GherkinAppStoriesDirective,
+    GherkinStoriesDirective,
+    GherkinStoriesForAppDirective,
+    GherkinStoriesForPersonaDirective,
+    GherkinStoriesIndexDirective,
+    GherkinStoryDirective,
+    StoriesDirective,
+    StoryAppDirective,
+    StoryIndexDirective,
+    StoryListForAppDirective,
+    StoryListForPersonaDirective,
+    StoryRefDirective,
+    StorySeeAlsoPlaceholder,
+    process_story_seealso_placeholders,
+)
+
+__all__ = [
+    # Base
+    "HCDDirective",
+    "make_deprecated_directive",
+    # Story directives
+    "StoryAppDirective",
+    "StoryListForPersonaDirective",
+    "StoryListForAppDirective",
+    "StoryIndexDirective",
+    "StoriesDirective",
+    "StoryRefDirective",
+    "StorySeeAlsoPlaceholder",
+    "process_story_seealso_placeholders",
+    # Story deprecated aliases
+    "GherkinStoryDirective",
+    "GherkinStoriesDirective",
+    "GherkinStoriesForPersonaDirective",
+    "GherkinStoriesForAppDirective",
+    "GherkinStoriesIndexDirective",
+    "GherkinAppStoriesDirective",
+    # Journey directives
+    "DefineJourneyDirective",
+    "StepStoryDirective",
+    "StepEpicDirective",
+    "StepPhaseDirective",
+    "JourneyIndexDirective",
+    "JourneyDependencyGraphDirective",
+    "JourneyDependencyGraphPlaceholder",
+    "JourneysForPersonaDirective",
+    "clear_journey_state",
+    "process_journey_steps",
+    "process_dependency_graph_placeholder",
+    # Epic directives
+    "DefineEpicDirective",
+    "EpicStoryDirective",
+    "EpicIndexDirective",
+    "EpicIndexPlaceholder",
+    "EpicsForPersonaDirective",
+    "EpicsForPersonaPlaceholder",
+    "clear_epic_state",
+    "process_epic_placeholders",
+    # App directives
+    "DefineAppDirective",
+    "DefineAppPlaceholder",
+    "AppIndexDirective",
+    "AppIndexPlaceholder",
+    "AppsForPersonaDirective",
+    "AppsForPersonaPlaceholder",
+    "process_app_placeholders",
+    # Accelerator directives
+    "DefineAcceleratorDirective",
+    "DefineAcceleratorPlaceholder",
+    "AcceleratorIndexDirective",
+    "AcceleratorIndexPlaceholder",
+    "AcceleratorsForAppDirective",
+    "AcceleratorsForAppPlaceholder",
+    "DependentAcceleratorsDirective",
+    "DependentAcceleratorsPlaceholder",
+    "AcceleratorDependencyDiagramDirective",
+    "AcceleratorDependencyDiagramPlaceholder",
+    "AcceleratorStatusDirective",
+    "clear_accelerator_state",
+    "process_accelerator_placeholders",
+    # Integration directives
+    "DefineIntegrationDirective",
+    "DefineIntegrationPlaceholder",
+    "IntegrationIndexDirective",
+    "IntegrationIndexPlaceholder",
+    "process_integration_placeholders",
+    # Persona directives
+    "PersonaDiagramDirective",
+    "PersonaDiagramPlaceholder",
+    "PersonaIndexDiagramDirective",
+    "PersonaIndexDiagramPlaceholder",
+    "process_persona_placeholders",
+]