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

julee/docs/sphinx_hcd/domain/models/story.py

@@ -0,0 +1,128 @@
+"""Story domain model.
+
+Represents a user story extracted from a Gherkin .feature file.
+"""
+
+from pydantic import BaseModel, field_validator
+
+from ...utils import normalize_name, slugify
+
+
+class Story(BaseModel):
+    """A user story extracted from a Gherkin feature file.
+
+    Stories are the primary unit of user-facing functionality in HCD.
+    They capture who wants to do what and why.
+
+    Attributes:
+        slug: URL-safe identifier derived from feature title
+        feature_title: The Feature: line from the Gherkin file
+        persona: The actor from "As a <persona>"
+        persona_normalized: Lowercase, spaces-normalized persona for matching
+        i_want: The action from "I want to <action>"
+        so_that: The benefit from "So that <benefit>"
+        app_slug: The application this story belongs to
+        app_normalized: Lowercase, spaces-normalized app name for matching
+        file_path: Relative path to the .feature file
+        abs_path: Absolute path to the .feature file
+        gherkin_snippet: The story header portion of the feature file
+    """
+
+    slug: str
+    feature_title: str
+    persona: str
+    persona_normalized: str = ""
+    i_want: str = "do something"
+    so_that: str = "achieve a goal"
+    app_slug: str
+    app_normalized: str = ""
+    file_path: str
+    abs_path: str = ""
+    gherkin_snippet: str = ""
+
+    @field_validator("slug")
+    @classmethod
+    def validate_slug(cls, v: str) -> str:
+        """Ensure slug is not empty."""
+        if not v or not v.strip():
+            raise ValueError("Story slug cannot be empty")
+        return v.strip()
+
+    @field_validator("feature_title")
+    @classmethod
+    def validate_feature_title(cls, v: str) -> str:
+        """Ensure feature title is not empty."""
+        if not v or not v.strip():
+            raise ValueError("Feature title cannot be empty")
+        return v.strip()
+
+    @field_validator("persona")
+    @classmethod
+    def validate_persona(cls, v: str) -> str:
+        """Ensure persona is not empty, default to 'unknown'."""
+        if not v or not v.strip():
+            return "unknown"
+        return v.strip()
+
+    @field_validator("app_slug")
+    @classmethod
+    def validate_app_slug(cls, v: str) -> str:
+        """Ensure app slug is not empty, default to 'unknown'."""
+        if not v or not v.strip():
+            return "unknown"
+        return v.strip()
+
+    def model_post_init(self, __context) -> None:
+        """Compute normalized fields after initialization."""
+        if not self.persona_normalized:
+            self.persona_normalized = normalize_name(self.persona)
+        if not self.app_normalized:
+            self.app_normalized = normalize_name(self.app_slug)
+
+    @classmethod
+    def from_feature_file(
+        cls,
+        feature_title: str,
+        persona: str,
+        i_want: str,
+        so_that: str,
+        app_slug: str,
+        file_path: str,
+        abs_path: str = "",
+        gherkin_snippet: str = "",
+    ) -> "Story":
+        """Create a Story from parsed feature file data.
+
+        Args:
+            feature_title: The Feature: line content
+            persona: The "As a" actor
+            i_want: The "I want to" action
+            so_that: The "So that" benefit
+            app_slug: Application slug (from directory structure)
+            file_path: Relative path to .feature file
+            abs_path: Absolute path to .feature file
+            gherkin_snippet: The story header text
+
+        Returns:
+            A new Story instance
+        """
+        # Include app_slug in slug to avoid collisions between apps
+        return cls(
+            slug=f"{app_slug}--{slugify(feature_title)}",
+            feature_title=feature_title,
+            persona=persona,
+            i_want=i_want,
+            so_that=so_that,
+            app_slug=app_slug,
+            file_path=file_path,
+            abs_path=abs_path,
+            gherkin_snippet=gherkin_snippet,
+        )
+
+    def matches_persona(self, persona_name: str) -> bool:
+        """Check if this story belongs to a persona (case-insensitive)."""
+        return self.persona_normalized == normalize_name(persona_name)
+
+    def matches_app(self, app_name: str) -> bool:
+        """Check if this story belongs to an app (case-insensitive)."""
+        return self.app_normalized == normalize_name(app_name)

julee/docs/sphinx_hcd/domain/repositories/__init__.py

@@ -0,0 +1,25 @@
+"""Repository protocols for sphinx_hcd.
+
+Defines async repository interfaces following julee patterns.
+Implementations live in the repositories/ directory.
+"""
+
+from .accelerator import AcceleratorRepository
+from .app import AppRepository
+from .base import BaseRepository
+from .code_info import CodeInfoRepository
+from .epic import EpicRepository
+from .integration import IntegrationRepository
+from .journey import JourneyRepository
+from .story import StoryRepository
+
+__all__ = [
+    "AcceleratorRepository",
+    "AppRepository",
+    "BaseRepository",
+    "CodeInfoRepository",
+    "EpicRepository",
+    "IntegrationRepository",
+    "JourneyRepository",
+    "StoryRepository",
+]

julee/docs/sphinx_hcd/domain/repositories/accelerator.py

@@ -0,0 +1,98 @@
+"""AcceleratorRepository protocol.
+
+Defines the interface for accelerator data access.
+"""
+
+from typing import Protocol, runtime_checkable
+
+from ..models.accelerator import Accelerator
+from .base import BaseRepository
+
+
+@runtime_checkable
+class AcceleratorRepository(BaseRepository[Accelerator], Protocol):
+    """Repository protocol for Accelerator entities.
+
+    Extends BaseRepository with accelerator-specific query methods.
+    Accelerators are defined in RST documents and support incremental builds
+    via docname tracking.
+    """
+
+    async def get_by_status(self, status: str) -> list[Accelerator]:
+        """Get all accelerators with a specific status.
+
+        Args:
+            status: Status to filter by (case-insensitive)
+
+        Returns:
+            List of accelerators with matching status
+        """
+        ...
+
+    async def get_by_docname(self, docname: str) -> list[Accelerator]:
+        """Get all accelerators defined in a specific document.
+
+        Args:
+            docname: RST document name
+
+        Returns:
+            List of accelerators from that document
+        """
+        ...
+
+    async def clear_by_docname(self, docname: str) -> int:
+        """Remove all accelerators defined in a specific document.
+
+        Used during incremental builds when a document is re-read.
+
+        Args:
+            docname: RST document name
+
+        Returns:
+            Number of accelerators removed
+        """
+        ...
+
+    async def get_by_integration(
+        self, integration_slug: str, relationship: str
+    ) -> list[Accelerator]:
+        """Get accelerators that have a relationship with an integration.
+
+        Args:
+            integration_slug: Integration slug to search for
+            relationship: Either "sources_from" or "publishes_to"
+
+        Returns:
+            List of accelerators with this integration relationship
+        """
+        ...
+
+    async def get_dependents(self, accelerator_slug: str) -> list[Accelerator]:
+        """Get accelerators that depend on a specific accelerator.
+
+        Args:
+            accelerator_slug: Slug of the accelerator to find dependents of
+
+        Returns:
+            List of accelerators that have this accelerator in depends_on
+        """
+        ...
+
+    async def get_fed_by(self, accelerator_slug: str) -> list[Accelerator]:
+        """Get accelerators that feed into a specific accelerator.
+
+        Args:
+            accelerator_slug: Slug of the accelerator
+
+        Returns:
+            List of accelerators that have this accelerator in feeds_into
+        """
+        ...
+
+    async def get_all_statuses(self) -> set[str]:
+        """Get all unique statuses across all accelerators.
+
+        Returns:
+            Set of status strings (normalized to lowercase)
+        """
+        ...

julee/docs/sphinx_hcd/domain/repositories/app.py

@@ -0,0 +1,57 @@
+"""AppRepository protocol.
+
+Defines the interface for app data access.
+"""
+
+from typing import Protocol, runtime_checkable
+
+from ..models.app import App, AppType
+from .base import BaseRepository
+
+
+@runtime_checkable
+class AppRepository(BaseRepository[App], Protocol):
+    """Repository protocol for App entities.
+
+    Extends BaseRepository with app-specific query methods.
+    Apps are indexed from YAML manifests and are read-only during
+    a Sphinx build (populated at builder-inited, queried during rendering).
+    """
+
+    async def get_by_type(self, app_type: AppType) -> list[App]:
+        """Get all apps of a specific type.
+
+        Args:
+            app_type: Application type to filter by
+
+        Returns:
+            List of apps matching the type
+        """
+        ...
+
+    async def get_by_name(self, name: str) -> App | None:
+        """Get an app by its display name (case-insensitive).
+
+        Args:
+            name: Display name to search for
+
+        Returns:
+            App if found, None otherwise
+        """
+        ...
+
+    async def get_all_types(self) -> set[AppType]:
+        """Get all unique app types that have apps.
+
+        Returns:
+            Set of app types with at least one app
+        """
+        ...
+
+    async def get_apps_with_accelerators(self) -> list[App]:
+        """Get all apps that have accelerators defined.
+
+        Returns:
+            List of apps with non-empty accelerators list
+        """
+        ...

julee/docs/sphinx_hcd/domain/repositories/base.py

@@ -0,0 +1,89 @@
+"""Base repository protocol for sphinx_hcd.
+
+Defines the generic repository interface following julee clean architecture
+patterns. All repository operations are async for consistency with julee,
+with sync adapters provided in the sphinx/ application layer.
+"""
+
+from typing import Protocol, TypeVar, runtime_checkable
+
+from pydantic import BaseModel
+
+T = TypeVar("T", bound=BaseModel)
+
+
+@runtime_checkable
+class BaseRepository(Protocol[T]):
+    """Generic base repository protocol for HCD entities.
+
+    This protocol defines the common interface shared by all domain
+    repositories in sphinx_hcd. It uses generics to provide type safety
+    while eliminating code duplication.
+
+    Type Parameter:
+        T: The domain entity type (must extend Pydantic BaseModel)
+
+    All methods are async for consistency with julee patterns. The sphinx/
+    application layer provides SyncRepositoryAdapter for use in Sphinx
+    directives which are synchronous.
+    """
+
+    async def get(self, entity_id: str) -> T | None:
+        """Retrieve an entity by ID.
+
+        Args:
+            entity_id: Unique entity identifier (typically a slug)
+
+        Returns:
+            Entity if found, None otherwise
+        """
+        ...
+
+    async def get_many(self, entity_ids: list[str]) -> dict[str, T | None]:
+        """Retrieve multiple entities by ID.
+
+        Args:
+            entity_ids: List of unique entity identifiers
+
+        Returns:
+            Dict mapping entity_id to entity (or None if not found)
+        """
+        ...
+
+    async def save(self, entity: T) -> None:
+        """Save an entity.
+
+        Args:
+            entity: Complete entity to save
+
+        Note:
+            Must be idempotent - saving the same entity state is safe.
+        """
+        ...
+
+    async def list_all(self) -> list[T]:
+        """List all entities.
+
+        Returns:
+            List of all entities in the repository
+        """
+        ...
+
+    async def delete(self, entity_id: str) -> bool:
+        """Delete an entity by ID.
+
+        Args:
+            entity_id: Unique entity identifier
+
+        Returns:
+            True if entity was deleted, False if not found
+        """
+        ...
+
+    async def clear(self) -> None:
+        """Remove all entities from the repository.
+
+        Used primarily for testing and re-initialization during
+        Sphinx incremental builds.
+        """
+        ...

julee/docs/sphinx_hcd/domain/repositories/code_info.py

@@ -0,0 +1,69 @@
+"""CodeInfoRepository protocol.
+
+Defines the interface for bounded context code introspection data access.
+"""
+
+from typing import Protocol, runtime_checkable
+
+from ..models.code_info import BoundedContextInfo
+from .base import BaseRepository
+
+
+@runtime_checkable
+class CodeInfoRepository(BaseRepository[BoundedContextInfo], Protocol):
+    """Repository protocol for BoundedContextInfo entities.
+
+    Extends BaseRepository with code introspection-specific query methods.
+    Code info is populated once at builder-inited by scanning src/ directories.
+    """
+
+    async def get_by_code_dir(self, code_dir: str) -> BoundedContextInfo | None:
+        """Get bounded context info by its code directory name.
+
+        Args:
+            code_dir: Directory name in src/ (may differ from slug)
+
+        Returns:
+            BoundedContextInfo if found, None otherwise
+        """
+        ...
+
+    async def get_with_entities(self) -> list[BoundedContextInfo]:
+        """Get all bounded contexts that have domain entities.
+
+        Returns:
+            List of bounded contexts with at least one entity
+        """
+        ...
+
+    async def get_with_use_cases(self) -> list[BoundedContextInfo]:
+        """Get all bounded contexts that have use cases.
+
+        Returns:
+            List of bounded contexts with at least one use case
+        """
+        ...
+
+    async def get_with_infrastructure(self) -> list[BoundedContextInfo]:
+        """Get all bounded contexts that have infrastructure.
+
+        Returns:
+            List of bounded contexts where has_infrastructure is True
+        """
+        ...
+
+    async def get_all_entity_names(self) -> set[str]:
+        """Get all unique entity class names across all bounded contexts.
+
+        Returns:
+            Set of entity class names
+        """
+        ...
+
+    async def get_all_use_case_names(self) -> set[str]:
+        """Get all unique use case class names across all bounded contexts.
+
+        Returns:
+            Set of use case class names
+        """
+        ...

julee/docs/sphinx_hcd/domain/repositories/epic.py

@@ -0,0 +1,62 @@
+"""EpicRepository protocol.
+
+Defines the interface for epic data access.
+"""
+
+from typing import Protocol, runtime_checkable
+
+from ..models.epic import Epic
+from .base import BaseRepository
+
+
+@runtime_checkable
+class EpicRepository(BaseRepository[Epic], Protocol):
+    """Repository protocol for Epic entities.
+
+    Extends BaseRepository with epic-specific query methods.
+    Epics are defined in RST documents and support incremental builds
+    via docname tracking.
+    """
+
+    async def get_by_docname(self, docname: str) -> list[Epic]:
+        """Get all epics defined in a specific document.
+
+        Args:
+            docname: RST document name
+
+        Returns:
+            List of epics from that document
+        """
+        ...
+
+    async def clear_by_docname(self, docname: str) -> int:
+        """Remove all epics defined in a specific document.
+
+        Used during incremental builds when a document is re-read.
+
+        Args:
+            docname: RST document name
+
+        Returns:
+            Number of epics removed
+        """
+        ...
+
+    async def get_with_story_ref(self, story_title: str) -> list[Epic]:
+        """Get epics that contain a specific story.
+
+        Args:
+            story_title: Story feature title (case-insensitive)
+
+        Returns:
+            List of epics containing this story in story_refs
+        """
+        ...
+
+    async def get_all_story_refs(self) -> set[str]:
+        """Get all unique story references across all epics.
+
+        Returns:
+            Set of story titles (normalized)
+        """
+        ...

julee/docs/sphinx_hcd/domain/repositories/integration.py

@@ -0,0 +1,79 @@
+"""IntegrationRepository protocol.
+
+Defines the interface for integration data access.
+"""
+
+from typing import Protocol, runtime_checkable
+
+from ..models.integration import Direction, Integration
+from .base import BaseRepository
+
+
+@runtime_checkable
+class IntegrationRepository(BaseRepository[Integration], Protocol):
+    """Repository protocol for Integration entities.
+
+    Extends BaseRepository with integration-specific query methods.
+    Integrations are indexed from YAML manifests and are read-only during
+    a Sphinx build (populated at builder-inited, queried during rendering).
+    """
+
+    async def get_by_direction(self, direction: Direction) -> list[Integration]:
+        """Get all integrations with a specific data flow direction.
+
+        Args:
+            direction: Direction to filter by
+
+        Returns:
+            List of integrations matching the direction
+        """
+        ...
+
+    async def get_by_module(self, module: str) -> Integration | None:
+        """Get an integration by its module name.
+
+        Args:
+            module: Python module name (e.g., "pilot_data_collection")
+
+        Returns:
+            Integration if found, None otherwise
+        """
+        ...
+
+    async def get_by_name(self, name: str) -> Integration | None:
+        """Get an integration by its display name (case-insensitive).
+
+        Args:
+            name: Display name to search for
+
+        Returns:
+            Integration if found, None otherwise
+        """
+        ...
+
+    async def get_all_directions(self) -> set[Direction]:
+        """Get all unique directions that have integrations.
+
+        Returns:
+            Set of directions with at least one integration
+        """
+        ...
+
+    async def get_with_dependencies(self) -> list[Integration]:
+        """Get all integrations that have external dependencies.
+
+        Returns:
+            List of integrations with non-empty depends_on list
+        """
+        ...
+
+    async def get_by_dependency(self, dep_name: str) -> list[Integration]:
+        """Get all integrations that depend on a specific external system.
+
+        Args:
+            dep_name: External dependency name (case-insensitive)
+
+        Returns:
+            List of integrations that have this dependency
+        """
+        ...