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

julee/docs/sphinx_hcd/parsers/yaml.py

@@ -0,0 +1,184 @@
+"""YAML manifest parsers.
+
+Parses YAML manifest files for apps and integrations.
+"""
+
+import logging
+from pathlib import Path
+
+import yaml
+
+from ..domain.models.app import App
+from ..domain.models.integration import Integration
+
+logger = logging.getLogger(__name__)
+
+
+def parse_app_manifest(manifest_path: Path, app_slug: str | None = None) -> App | None:
+    """Parse an app.yaml manifest file.
+
+    Args:
+        manifest_path: Path to the app.yaml file
+        app_slug: Optional app slug override. If None, extracted from directory name.
+
+    Returns:
+        App entity, or None if parsing fails
+    """
+    try:
+        content = manifest_path.read_text()
+    except Exception as e:
+        logger.warning(f"Could not read {manifest_path}: {e}")
+        return None
+
+    try:
+        manifest = yaml.safe_load(content)
+    except yaml.YAMLError as e:
+        logger.warning(f"Could not parse YAML in {manifest_path}: {e}")
+        return None
+
+    if manifest is None:
+        logger.warning(f"Empty manifest at {manifest_path}")
+        return None
+
+    # Extract app slug from directory name if not provided
+    if app_slug is None:
+        app_slug = manifest_path.parent.name
+
+    return App.from_manifest(
+        slug=app_slug,
+        manifest=manifest,
+        manifest_path=str(manifest_path),
+    )
+
+
+def scan_app_manifests(apps_dir: Path) -> list[App]:
+    """Scan a directory for app.yaml manifest files.
+
+    Expects structure: apps_dir/{app-slug}/app.yaml
+
+    Args:
+        apps_dir: Directory containing app subdirectories
+
+    Returns:
+        List of parsed App entities
+    """
+    apps = []
+
+    if not apps_dir.exists():
+        logger.info(
+            f"Apps directory not found at {apps_dir} - no app manifests to index"
+        )
+        return apps
+
+    for app_dir in apps_dir.iterdir():
+        if not app_dir.is_dir():
+            continue
+
+        manifest_path = app_dir / "app.yaml"
+        if not manifest_path.exists():
+            continue
+
+        app = parse_app_manifest(manifest_path)
+        if app:
+            apps.append(app)
+
+    logger.info(f"Indexed {len(apps)} apps from {apps_dir}")
+    return apps
+
+
+def parse_manifest_content(content: str) -> dict | None:
+    """Parse YAML content string.
+
+    A lower-level helper for testing and direct content parsing.
+
+    Args:
+        content: YAML content string
+
+    Returns:
+        Parsed dictionary, or None if parsing fails
+    """
+    try:
+        return yaml.safe_load(content)
+    except yaml.YAMLError as e:
+        logger.warning(f"Could not parse YAML content: {e}")
+        return None
+
+
+# Integration manifest parsing
+
+
+def parse_integration_manifest(
+    manifest_path: Path, module_name: str | None = None
+) -> Integration | None:
+    """Parse an integration.yaml manifest file.
+
+    Args:
+        manifest_path: Path to the integration.yaml file
+        module_name: Optional module name override. If None, extracted from directory name.
+
+    Returns:
+        Integration entity, or None if parsing fails
+    """
+    try:
+        content = manifest_path.read_text()
+    except Exception as e:
+        logger.warning(f"Could not read {manifest_path}: {e}")
+        return None
+
+    try:
+        manifest = yaml.safe_load(content)
+    except yaml.YAMLError as e:
+        logger.warning(f"Could not parse YAML in {manifest_path}: {e}")
+        return None
+
+    if manifest is None:
+        logger.warning(f"Empty manifest at {manifest_path}")
+        return None
+
+    # Extract module name from directory name if not provided
+    if module_name is None:
+        module_name = manifest_path.parent.name
+
+    return Integration.from_manifest(
+        module_name=module_name,
+        manifest=manifest,
+        manifest_path=str(manifest_path),
+    )
+
+
+def scan_integration_manifests(integrations_dir: Path) -> list[Integration]:
+    """Scan a directory for integration.yaml manifest files.
+
+    Expects structure: integrations_dir/{module_name}/integration.yaml
+    Directories starting with '_' are skipped.
+
+    Args:
+        integrations_dir: Directory containing integration subdirectories
+
+    Returns:
+        List of parsed Integration entities
+    """
+    integrations = []
+
+    if not integrations_dir.exists():
+        logger.info(
+            f"Integrations directory not found at {integrations_dir} - "
+            "no integration manifests to index"
+        )
+        return integrations
+
+    for int_dir in integrations_dir.iterdir():
+        # Skip non-directories and directories starting with '_'
+        if not int_dir.is_dir() or int_dir.name.startswith("_"):
+            continue
+
+        manifest_path = int_dir / "integration.yaml"
+        if not manifest_path.exists():
+            continue
+
+        integration = parse_integration_manifest(manifest_path)
+        if integration:
+            integrations.append(integration)
+
+    logger.info(f"Indexed {len(integrations)} integrations from {integrations_dir}")
+    return integrations

julee/docs/sphinx_hcd/repositories/__init__.py

@@ -0,0 +1,4 @@
+"""Repository implementations for sphinx_hcd.
+
+Contains memory repository implementations following julee patterns.
+"""

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

@@ -0,0 +1,25 @@
+"""Memory repository implementations for sphinx_hcd.
+
+In-memory implementations used during Sphinx builds. These repositories
+are populated at builder-inited and queried during doctree processing.
+"""
+
+from .accelerator import MemoryAcceleratorRepository
+from .app import MemoryAppRepository
+from .base import MemoryRepositoryMixin
+from .code_info import MemoryCodeInfoRepository
+from .epic import MemoryEpicRepository
+from .integration import MemoryIntegrationRepository
+from .journey import MemoryJourneyRepository
+from .story import MemoryStoryRepository
+
+__all__ = [
+    "MemoryAcceleratorRepository",
+    "MemoryAppRepository",
+    "MemoryCodeInfoRepository",
+    "MemoryEpicRepository",
+    "MemoryIntegrationRepository",
+    "MemoryJourneyRepository",
+    "MemoryRepositoryMixin",
+    "MemoryStoryRepository",
+]

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

@@ -0,0 +1,86 @@
+"""Memory implementation of AcceleratorRepository."""
+
+import logging
+
+from ...domain.models.accelerator import Accelerator
+from ...domain.repositories.accelerator import AcceleratorRepository
+from .base import MemoryRepositoryMixin
+
+logger = logging.getLogger(__name__)
+
+
+class MemoryAcceleratorRepository(
+    MemoryRepositoryMixin[Accelerator], AcceleratorRepository
+):
+    """In-memory implementation of AcceleratorRepository.
+
+    Accelerators are stored in a dictionary keyed by slug. This implementation
+    is used during Sphinx builds where accelerators are populated during doctree
+    processing and support incremental builds via docname tracking.
+    """
+
+    def __init__(self) -> None:
+        """Initialize with empty storage."""
+        self.storage: dict[str, Accelerator] = {}
+        self.entity_name = "Accelerator"
+        self.id_field = "slug"
+
+    async def get_by_status(self, status: str) -> list[Accelerator]:
+        """Get all accelerators with a specific status."""
+        status_normalized = status.lower().strip()
+        return [
+            accel
+            for accel in self.storage.values()
+            if accel.status_normalized == status_normalized
+        ]
+
+    async def get_by_docname(self, docname: str) -> list[Accelerator]:
+        """Get all accelerators defined in a specific document."""
+        return [accel for accel in self.storage.values() if accel.docname == docname]
+
+    async def clear_by_docname(self, docname: str) -> int:
+        """Remove all accelerators defined in a specific document."""
+        to_remove = [
+            slug for slug, accel in self.storage.items() if accel.docname == docname
+        ]
+        for slug in to_remove:
+            del self.storage[slug]
+        return len(to_remove)
+
+    async def get_by_integration(
+        self, integration_slug: str, relationship: str
+    ) -> list[Accelerator]:
+        """Get accelerators that have a relationship with an integration."""
+        result = []
+        for accel in self.storage.values():
+            if relationship == "sources_from":
+                if integration_slug in accel.get_sources_from_slugs():
+                    result.append(accel)
+            elif relationship == "publishes_to":
+                if integration_slug in accel.get_publishes_to_slugs():
+                    result.append(accel)
+        return result
+
+    async def get_dependents(self, accelerator_slug: str) -> list[Accelerator]:
+        """Get accelerators that depend on a specific accelerator."""
+        return [
+            accel
+            for accel in self.storage.values()
+            if accelerator_slug in accel.depends_on
+        ]
+
+    async def get_fed_by(self, accelerator_slug: str) -> list[Accelerator]:
+        """Get accelerators that feed into a specific accelerator."""
+        return [
+            accel
+            for accel in self.storage.values()
+            if accelerator_slug in accel.feeds_into
+        ]
+
+    async def get_all_statuses(self) -> set[str]:
+        """Get all unique statuses across all accelerators."""
+        return {
+            accel.status_normalized
+            for accel in self.storage.values()
+            if accel.status_normalized
+        }

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

@@ -0,0 +1,45 @@
+"""Memory implementation of AppRepository."""
+
+import logging
+
+from ...domain.models.app import App, AppType
+from ...domain.repositories.app import AppRepository
+from ...utils import normalize_name
+from .base import MemoryRepositoryMixin
+
+logger = logging.getLogger(__name__)
+
+
+class MemoryAppRepository(MemoryRepositoryMixin[App], AppRepository):
+    """In-memory implementation of AppRepository.
+
+    Apps are stored in a dictionary keyed by slug. This implementation
+    is used during Sphinx builds where apps are populated at builder-inited
+    and queried during doctree processing.
+    """
+
+    def __init__(self) -> None:
+        """Initialize with empty storage."""
+        self.storage: dict[str, App] = {}
+        self.entity_name = "App"
+        self.id_field = "slug"
+
+    async def get_by_type(self, app_type: AppType) -> list[App]:
+        """Get all apps of a specific type."""
+        return [app for app in self.storage.values() if app.app_type == app_type]
+
+    async def get_by_name(self, name: str) -> App | None:
+        """Get an app by its display name (case-insensitive)."""
+        name_normalized = normalize_name(name)
+        for app in self.storage.values():
+            if app.name_normalized == name_normalized:
+                return app
+        return None
+
+    async def get_all_types(self) -> set[AppType]:
+        """Get all unique app types that have apps."""
+        return {app.app_type for app in self.storage.values()}
+
+    async def get_apps_with_accelerators(self) -> list[App]:
+        """Get all apps that have accelerators defined."""
+        return [app for app in self.storage.values() if app.accelerators]

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

@@ -0,0 +1,106 @@
+"""Memory repository base classes and mixins for sphinx_hcd.
+
+Provides common functionality for in-memory repository implementations,
+following julee patterns but simplified for sphinx_hcd's needs.
+"""
+
+import logging
+from typing import Any, Generic, TypeVar
+
+from pydantic import BaseModel
+
+T = TypeVar("T", bound=BaseModel)
+
+logger = logging.getLogger(__name__)
+
+
+class MemoryRepositoryMixin(Generic[T]):
+    """Mixin providing common repository patterns for memory implementations.
+
+    Encapsulates common functionality used across all memory repository
+    implementations:
+    - Dictionary-based entity storage and retrieval
+    - Standardized logging patterns
+    - Generic CRUD operations
+
+    Classes using this mixin must provide:
+    - self.storage: dict[str, T] for entity storage
+    - self.entity_name: str for logging
+    - self.id_field: str naming the entity's ID field
+    """
+
+    storage: dict[str, T]
+    entity_name: str
+    id_field: str
+
+    def _get_entity_id(self, entity: T) -> str:
+        """Extract the entity ID from an entity instance."""
+        return getattr(entity, self.id_field)
+
+    async def get(self, entity_id: str) -> T | None:
+        """Retrieve an entity by ID."""
+        entity = self.storage.get(entity_id)
+        if entity is None:
+            logger.debug(
+                f"Memory{self.entity_name}Repository: {self.entity_name} not found",
+                extra={f"{self.entity_name.lower()}_id": entity_id},
+            )
+        return entity
+
+    async def get_many(self, entity_ids: list[str]) -> dict[str, T | None]:
+        """Retrieve multiple entities by ID."""
+        result: dict[str, T | None] = {}
+        for entity_id in entity_ids:
+            result[entity_id] = self.storage.get(entity_id)
+        return result
+
+    async def save(self, entity: T) -> None:
+        """Save an entity to storage."""
+        entity_id = self._get_entity_id(entity)
+        self.storage[entity_id] = entity
+        logger.debug(
+            f"Memory{self.entity_name}Repository: Saved {self.entity_name}",
+            extra={f"{self.entity_name.lower()}_id": entity_id},
+        )
+
+    async def list_all(self) -> list[T]:
+        """List all entities."""
+        return list(self.storage.values())
+
+    async def delete(self, entity_id: str) -> bool:
+        """Delete an entity by ID."""
+        if entity_id in self.storage:
+            del self.storage[entity_id]
+            logger.debug(
+                f"Memory{self.entity_name}Repository: Deleted {self.entity_name}",
+                extra={f"{self.entity_name.lower()}_id": entity_id},
+            )
+            return True
+        return False
+
+    async def clear(self) -> None:
+        """Remove all entities from storage."""
+        count = len(self.storage)
+        self.storage.clear()
+        logger.debug(
+            f"Memory{self.entity_name}Repository: Cleared {count} entities",
+        )
+
+    # Additional query methods that subclasses can use
+
+    async def find_by_field(self, field: str, value: Any) -> list[T]:
+        """Find all entities where field equals value."""
+        return [
+            entity
+            for entity in self.storage.values()
+            if getattr(entity, field, None) == value
+        ]
+
+    async def find_by_field_in(self, field: str, values: list[Any]) -> list[T]:
+        """Find all entities where field is in values."""
+        value_set = set(values)
+        return [
+            entity
+            for entity in self.storage.values()
+            if getattr(entity, field, None) in value_set
+        ]

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

@@ -0,0 +1,59 @@
+"""Memory implementation of CodeInfoRepository."""
+
+import logging
+
+from ...domain.models.code_info import BoundedContextInfo
+from ...domain.repositories.code_info import CodeInfoRepository
+from .base import MemoryRepositoryMixin
+
+logger = logging.getLogger(__name__)
+
+
+class MemoryCodeInfoRepository(
+    MemoryRepositoryMixin[BoundedContextInfo], CodeInfoRepository
+):
+    """In-memory implementation of CodeInfoRepository.
+
+    Bounded context info is stored in a dictionary keyed by slug. This implementation
+    is used during Sphinx builds where code info is populated at builder-inited
+    by scanning src/ directories.
+    """
+
+    def __init__(self) -> None:
+        """Initialize with empty storage."""
+        self.storage: dict[str, BoundedContextInfo] = {}
+        self.entity_name = "BoundedContextInfo"
+        self.id_field = "slug"
+
+    async def get_by_code_dir(self, code_dir: str) -> BoundedContextInfo | None:
+        """Get bounded context info by its code directory name."""
+        for info in self.storage.values():
+            if info.code_dir == code_dir:
+                return info
+        return None
+
+    async def get_with_entities(self) -> list[BoundedContextInfo]:
+        """Get all bounded contexts that have domain entities."""
+        return [info for info in self.storage.values() if info.has_entities]
+
+    async def get_with_use_cases(self) -> list[BoundedContextInfo]:
+        """Get all bounded contexts that have use cases."""
+        return [info for info in self.storage.values() if info.has_use_cases]
+
+    async def get_with_infrastructure(self) -> list[BoundedContextInfo]:
+        """Get all bounded contexts that have infrastructure."""
+        return [info for info in self.storage.values() if info.has_infrastructure]
+
+    async def get_all_entity_names(self) -> set[str]:
+        """Get all unique entity class names across all bounded contexts."""
+        names: set[str] = set()
+        for info in self.storage.values():
+            names.update(info.get_entity_names())
+        return names
+
+    async def get_all_use_case_names(self) -> set[str]:
+        """Get all unique use case class names across all bounded contexts."""
+        names: set[str] = set()
+        for info in self.storage.values():
+            names.update(info.get_use_case_names())
+        return names

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

@@ -0,0 +1,54 @@
+"""Memory implementation of EpicRepository."""
+
+import logging
+
+from ...domain.models.epic import Epic
+from ...domain.repositories.epic import EpicRepository
+from ...utils import normalize_name
+from .base import MemoryRepositoryMixin
+
+logger = logging.getLogger(__name__)
+
+
+class MemoryEpicRepository(MemoryRepositoryMixin[Epic], EpicRepository):
+    """In-memory implementation of EpicRepository.
+
+    Epics are stored in a dictionary keyed by slug. This implementation
+    is used during Sphinx builds where epics are populated during doctree
+    processing and support incremental builds via docname tracking.
+    """
+
+    def __init__(self) -> None:
+        """Initialize with empty storage."""
+        self.storage: dict[str, Epic] = {}
+        self.entity_name = "Epic"
+        self.id_field = "slug"
+
+    async def get_by_docname(self, docname: str) -> list[Epic]:
+        """Get all epics defined in a specific document."""
+        return [epic for epic in self.storage.values() if epic.docname == docname]
+
+    async def clear_by_docname(self, docname: str) -> int:
+        """Remove all epics defined in a specific document."""
+        to_remove = [
+            slug for slug, epic in self.storage.items() if epic.docname == docname
+        ]
+        for slug in to_remove:
+            del self.storage[slug]
+        return len(to_remove)
+
+    async def get_with_story_ref(self, story_title: str) -> list[Epic]:
+        """Get epics that contain a specific story."""
+        story_normalized = normalize_name(story_title)
+        return [
+            epic
+            for epic in self.storage.values()
+            if any(normalize_name(ref) == story_normalized for ref in epic.story_refs)
+        ]
+
+    async def get_all_story_refs(self) -> set[str]:
+        """Get all unique story references across all epics."""
+        refs: set[str] = set()
+        for epic in self.storage.values():
+            refs.update(normalize_name(ref) for ref in epic.story_refs)
+        return refs

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

@@ -0,0 +1,70 @@
+"""Memory implementation of IntegrationRepository."""
+
+import logging
+
+from ...domain.models.integration import Direction, Integration
+from ...domain.repositories.integration import IntegrationRepository
+from ...utils import normalize_name
+from .base import MemoryRepositoryMixin
+
+logger = logging.getLogger(__name__)
+
+
+class MemoryIntegrationRepository(
+    MemoryRepositoryMixin[Integration], IntegrationRepository
+):
+    """In-memory implementation of IntegrationRepository.
+
+    Integrations are stored in a dictionary keyed by slug. This implementation
+    is used during Sphinx builds where integrations are populated at builder-inited
+    and queried during doctree processing.
+    """
+
+    def __init__(self) -> None:
+        """Initialize with empty storage."""
+        self.storage: dict[str, Integration] = {}
+        self.entity_name = "Integration"
+        self.id_field = "slug"
+
+    async def get_by_direction(self, direction: Direction) -> list[Integration]:
+        """Get all integrations with a specific direction."""
+        return [
+            integration
+            for integration in self.storage.values()
+            if integration.direction == direction
+        ]
+
+    async def get_by_module(self, module: str) -> Integration | None:
+        """Get an integration by its module name."""
+        for integration in self.storage.values():
+            if integration.module == module:
+                return integration
+        return None
+
+    async def get_by_name(self, name: str) -> Integration | None:
+        """Get an integration by its display name (case-insensitive)."""
+        name_normalized = normalize_name(name)
+        for integration in self.storage.values():
+            if integration.name_normalized == name_normalized:
+                return integration
+        return None
+
+    async def get_all_directions(self) -> set[Direction]:
+        """Get all unique directions that have integrations."""
+        return {integration.direction for integration in self.storage.values()}
+
+    async def get_with_dependencies(self) -> list[Integration]:
+        """Get all integrations that have external dependencies."""
+        return [
+            integration
+            for integration in self.storage.values()
+            if integration.depends_on
+        ]
+
+    async def get_by_dependency(self, dep_name: str) -> list[Integration]:
+        """Get all integrations that depend on a specific external system."""
+        return [
+            integration
+            for integration in self.storage.values()
+            if integration.has_dependency(dep_name)
+        ]