julee 0.1.5__py3-none-any.whl → 0.1.7__py3-none-any.whl

julee/docs/sphinx_hcd/repositories/memory/journey.py

@@ -0,0 +1,96 @@
+"""Memory implementation of JourneyRepository."""
+
+import logging
+
+from ...domain.models.journey import Journey
+from ...domain.repositories.journey import JourneyRepository
+from ...utils import normalize_name
+from .base import MemoryRepositoryMixin
+
+logger = logging.getLogger(__name__)
+
+
+class MemoryJourneyRepository(MemoryRepositoryMixin[Journey], JourneyRepository):
+    """In-memory implementation of JourneyRepository.
+
+    Journeys are stored in a dictionary keyed by slug. This implementation
+    is used during Sphinx builds where journeys are populated during doctree
+    processing and support incremental builds via docname tracking.
+    """
+
+    def __init__(self) -> None:
+        """Initialize with empty storage."""
+        self.storage: dict[str, Journey] = {}
+        self.entity_name = "Journey"
+        self.id_field = "slug"
+
+    async def get_by_persona(self, persona: str) -> list[Journey]:
+        """Get all journeys for a persona."""
+        persona_normalized = normalize_name(persona)
+        return [
+            journey
+            for journey in self.storage.values()
+            if journey.persona_normalized == persona_normalized
+        ]
+
+    async def get_by_docname(self, docname: str) -> list[Journey]:
+        """Get all journeys defined in a specific document."""
+        return [
+            journey for journey in self.storage.values() if journey.docname == docname
+        ]
+
+    async def clear_by_docname(self, docname: str) -> int:
+        """Remove all journeys defined in a specific document."""
+        to_remove = [
+            slug for slug, journey in self.storage.items() if journey.docname == docname
+        ]
+        for slug in to_remove:
+            del self.storage[slug]
+        return len(to_remove)
+
+    async def get_dependents(self, journey_slug: str) -> list[Journey]:
+        """Get journeys that depend on a specific journey."""
+        return [
+            journey
+            for journey in self.storage.values()
+            if journey.has_dependency(journey_slug)
+        ]
+
+    async def get_dependencies(self, journey_slug: str) -> list[Journey]:
+        """Get journeys that a specific journey depends on."""
+        journey = self.storage.get(journey_slug)
+        if not journey:
+            return []
+        return [
+            self.storage[dep_slug]
+            for dep_slug in journey.depends_on
+            if dep_slug in self.storage
+        ]
+
+    async def get_all_personas(self) -> set[str]:
+        """Get all unique personas across all journeys."""
+        return {
+            journey.persona_normalized
+            for journey in self.storage.values()
+            if journey.persona_normalized
+        }
+
+    async def get_with_story_ref(self, story_title: str) -> list[Journey]:
+        """Get journeys that reference a specific story."""
+        story_normalized = normalize_name(story_title)
+        return [
+            journey
+            for journey in self.storage.values()
+            if any(
+                normalize_name(ref) == story_normalized
+                for ref in journey.get_story_refs()
+            )
+        ]
+
+    async def get_with_epic_ref(self, epic_slug: str) -> list[Journey]:
+        """Get journeys that reference a specific epic."""
+        return [
+            journey
+            for journey in self.storage.values()
+            if epic_slug in journey.get_epic_refs()
+        ]

julee/docs/sphinx_hcd/repositories/memory/story.py

@@ -0,0 +1,63 @@
+"""Memory implementation of StoryRepository."""
+
+import logging
+
+from ...domain.models.story import Story
+from ...domain.repositories.story import StoryRepository
+from ...utils import normalize_name
+from .base import MemoryRepositoryMixin
+
+logger = logging.getLogger(__name__)
+
+
+class MemoryStoryRepository(MemoryRepositoryMixin[Story], StoryRepository):
+    """In-memory implementation of StoryRepository.
+
+    Stories are stored in a dictionary keyed by slug. This implementation
+    is used during Sphinx builds where stories are populated at builder-inited
+    and queried during doctree processing.
+    """
+
+    def __init__(self) -> None:
+        """Initialize with empty storage."""
+        self.storage: dict[str, Story] = {}
+        self.entity_name = "Story"
+        self.id_field = "slug"
+
+    async def get_by_app(self, app_slug: str) -> list[Story]:
+        """Get all stories for an application."""
+        app_normalized = normalize_name(app_slug)
+        return [
+            story
+            for story in self.storage.values()
+            if story.app_normalized == app_normalized
+        ]
+
+    async def get_by_persona(self, persona: str) -> list[Story]:
+        """Get all stories for a persona."""
+        persona_normalized = normalize_name(persona)
+        return [
+            story
+            for story in self.storage.values()
+            if story.persona_normalized == persona_normalized
+        ]
+
+    async def get_by_feature_title(self, feature_title: str) -> Story | None:
+        """Get a story by its feature title."""
+        title_normalized = normalize_name(feature_title)
+        for story in self.storage.values():
+            if normalize_name(story.feature_title) == title_normalized:
+                return story
+        return None
+
+    async def get_apps_with_stories(self) -> set[str]:
+        """Get the set of app slugs that have stories."""
+        return {story.app_slug for story in self.storage.values()}
+
+    async def get_all_personas(self) -> set[str]:
+        """Get all unique personas across all stories."""
+        return {
+            story.persona_normalized
+            for story in self.storage.values()
+            if story.persona_normalized != "unknown"
+        }

julee/docs/sphinx_hcd/sphinx/__init__.py

@@ -0,0 +1,28 @@
+"""Sphinx application layer for sphinx_hcd.
+
+Contains Sphinx-specific code:
+- adapters.py: SyncRepositoryAdapter for sync access to async repos
+- context.py: HCDContext for unified repository access
+- initialization.py: Builder-inited handlers
+- directives/: Sphinx directive implementations
+- event_handlers/: Sphinx lifecycle event handlers
+"""
+
+from .adapters import SyncRepositoryAdapter
+from .context import (
+    HCDContext,
+    ensure_hcd_context,
+    get_hcd_context,
+    set_hcd_context,
+)
+from .initialization import initialize_hcd_context, purge_doc_from_context
+
+__all__ = [
+    "HCDContext",
+    "SyncRepositoryAdapter",
+    "ensure_hcd_context",
+    "get_hcd_context",
+    "initialize_hcd_context",
+    "purge_doc_from_context",
+    "set_hcd_context",
+]

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",
+]