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

julee/docs/sphinx_hcd/sphinx/event_handlers/env_purge_doc.py

@@ -0,0 +1,42 @@
+"""Env-purge-doc event handler for sphinx_hcd.
+
+Clears document-specific state when a document is re-read.
+"""
+
+from ..directives import (
+    clear_accelerator_state,
+    clear_epic_state,
+    clear_journey_state,
+)
+
+
+def on_env_purge_doc(app, env, docname):
+    """Clear state when a document is re-read.
+
+    This handler runs when a document needs to be re-read (incremental build).
+    It clears any state associated with that document.
+
+    Args:
+        app: Sphinx application instance
+        env: Sphinx build environment
+        docname: The document name being purged
+    """
+    # Clear epic state for this document
+    clear_epic_state(app, env, docname)
+
+    # Clear journey state for this document
+    clear_journey_state(app, env, docname)
+
+    # Clear accelerator state for this document
+    clear_accelerator_state(app, env, docname)
+
+    # Clear documented apps tracker
+    if hasattr(env, "documented_apps") and docname in env.documented_apps:
+        env.documented_apps.discard(docname)
+
+    # Clear documented integrations tracker
+    if (
+        hasattr(env, "documented_integrations")
+        and docname in env.documented_integrations
+    ):
+        env.documented_integrations.discard(docname)

julee/docs/sphinx_hcd/sphinx/initialization.py

@@ -0,0 +1,139 @@
+"""Sphinx initialization handlers for HCD context.
+
+Handles builder-inited event to set up the HCDContext and populate
+repositories with data that doesn't change during the build.
+"""
+
+import logging
+
+from ..config import get_config
+from ..parsers import (
+    scan_app_manifests,
+    scan_bounded_contexts,
+    scan_feature_directory,
+    scan_integration_manifests,
+)
+from .context import HCDContext, set_hcd_context
+
+logger = logging.getLogger(__name__)
+
+
+def initialize_hcd_context(app) -> None:
+    """Initialize HCDContext at builder-inited.
+
+    Creates the context and populates repositories with data that is
+    static during the build:
+    - Stories (from .feature files)
+    - Apps (from app.yaml manifests)
+    - Integrations (from integration.yaml manifests)
+    - Code info (from src/ introspection)
+
+    Journeys, epics, and accelerators are populated during doctree
+    processing as they're defined in RST files.
+
+    Args:
+        app: Sphinx application object
+    """
+    context = HCDContext()
+    set_hcd_context(app, context)
+
+    config = get_config()
+
+    # Load stories from feature files
+    _load_stories(context, config)
+
+    # Load apps from manifests
+    _load_apps(context, config)
+
+    # Load integrations from manifests
+    _load_integrations(context, config)
+
+    # Load code info from src/ introspection
+    _load_code_info(context, config)
+
+    logger.info("HCDContext initialized")
+
+
+def _load_stories(context: HCDContext, config) -> None:
+    """Load stories from feature files into the repository."""
+    features_dir = config.get_path("feature_files")
+    if not features_dir.exists():
+        logger.info(f"Features directory not found: {features_dir}")
+        return
+
+    stories = scan_feature_directory(features_dir, config.project_root)
+    for story in stories:
+        context.story_repo.save(story)
+
+    logger.info(f"Loaded {len(stories)} stories from feature files")
+
+
+def _load_apps(context: HCDContext, config) -> None:
+    """Load apps from manifest files into the repository."""
+    apps_dir = config.get_path("app_manifests")
+    if not apps_dir.exists():
+        logger.info(f"Applications directory not found: {apps_dir}")
+        return
+
+    apps = scan_app_manifests(apps_dir)
+    for app in apps:
+        context.app_repo.save(app)
+
+    logger.info(f"Loaded {len(apps)} apps from manifests")
+
+
+def _load_integrations(context: HCDContext, config) -> None:
+    """Load integrations from manifest files into the repository."""
+    integrations_dir = config.get_path("integration_manifests")
+    if not integrations_dir.exists():
+        logger.info(f"Integrations directory not found: {integrations_dir}")
+        return
+
+    integrations = scan_integration_manifests(integrations_dir)
+    for integration in integrations:
+        context.integration_repo.save(integration)
+
+    logger.info(f"Loaded {len(integrations)} integrations from manifests")
+
+
+def _load_code_info(context: HCDContext, config) -> None:
+    """Load code info from src/ introspection into the repository."""
+    src_dir = config.get_path("bounded_contexts")
+    if not src_dir.exists():
+        logger.info(f"Source directory not found: {src_dir}")
+        return
+
+    contexts = scan_bounded_contexts(src_dir)
+    for code_info in contexts:
+        context.code_info_repo.save(code_info)
+
+    logger.info(f"Loaded {len(contexts)} bounded contexts from source")
+
+
+def purge_doc_from_context(app, env, docname: str) -> None:
+    """Purge entities from a document when it's being re-read.
+
+    Called during env-purge-doc event for incremental builds.
+
+    Args:
+        app: Sphinx application object
+        env: Sphinx environment
+        docname: Document being purged
+    """
+    from .context import get_hcd_context
+
+    try:
+        context = get_hcd_context(app)
+        results = context.clear_by_docname(docname)
+
+        total = sum(results.values())
+        if total > 0:
+            logger.debug(
+                f"Purged from {docname}: "
+                f"{results.get('journeys', 0)} journeys, "
+                f"{results.get('epics', 0)} epics, "
+                f"{results.get('accelerators', 0)} accelerators"
+            )
+    except AttributeError:
+        # Context not initialized yet - this is fine during startup
+        pass

julee/docs/sphinx_hcd/tests/__init__.py

@@ -0,0 +1,9 @@
+"""Tests for sphinx_hcd.
+
+Organized by layer:
+- domain/: Domain model and use case tests
+- repositories/: Repository implementation tests
+- parsers/: Parser tests
+- sphinx/: Sphinx adapter and directive tests
+- integration/: Full Sphinx build tests
+"""

julee/docs/sphinx_hcd/tests/conftest.py

@@ -0,0 +1,6 @@
+"""Pytest configuration and fixtures for sphinx_hcd tests."""
+
+import pytest
+
+# Mark all tests in this directory as unit tests by default
+pytestmark = pytest.mark.unit

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

@@ -0,0 +1 @@
+"""Domain layer tests."""

julee/docs/sphinx_hcd/tests/domain/models/__init__.py

@@ -0,0 +1 @@
+"""Domain model tests."""

julee/docs/sphinx_hcd/tests/domain/models/test_accelerator.py

@@ -0,0 +1,266 @@
+"""Tests for Accelerator domain model."""
+
+import pytest
+from pydantic import ValidationError
+
+from julee.docs.sphinx_hcd.domain.models.accelerator import (
+    Accelerator,
+    IntegrationReference,
+)
+
+
+class TestIntegrationReference:
+    """Test IntegrationReference model."""
+
+    def test_create_with_slug_only(self) -> None:
+        """Test creating with just slug."""
+        ref = IntegrationReference(slug="pilot-data")
+        assert ref.slug == "pilot-data"
+        assert ref.description == ""
+
+    def test_create_with_description(self) -> None:
+        """Test creating with description."""
+        ref = IntegrationReference(
+            slug="pilot-data",
+            description="Scheme documentation, standards materials",
+        )
+        assert ref.slug == "pilot-data"
+        assert ref.description == "Scheme documentation, standards materials"
+
+    def test_empty_slug_raises_error(self) -> None:
+        """Test that empty slug raises validation error."""
+        with pytest.raises(ValidationError, match="slug cannot be empty"):
+            IntegrationReference(slug="")
+
+    def test_from_dict_complete(self) -> None:
+        """Test from_dict with full dict."""
+        ref = IntegrationReference.from_dict(
+            {
+                "slug": "pilot-data",
+                "description": "Test description",
+            }
+        )
+        assert ref.slug == "pilot-data"
+        assert ref.description == "Test description"
+
+    def test_from_dict_string(self) -> None:
+        """Test from_dict with plain string."""
+        ref = IntegrationReference.from_dict("pilot-data")
+        assert ref.slug == "pilot-data"
+        assert ref.description == ""
+
+    def test_from_dict_minimal(self) -> None:
+        """Test from_dict with minimal dict."""
+        ref = IntegrationReference.from_dict({"slug": "pilot-data"})
+        assert ref.slug == "pilot-data"
+        assert ref.description == ""
+
+
+class TestAcceleratorCreation:
+    """Test Accelerator model creation and validation."""
+
+    def test_create_accelerator_minimal(self) -> None:
+        """Test creating an accelerator with minimum fields."""
+        accel = Accelerator(slug="vocabulary")
+        assert accel.slug == "vocabulary"
+        assert accel.status == ""
+        assert accel.milestone is None
+        assert accel.acceptance is None
+        assert accel.objective == ""
+        assert accel.sources_from == []
+        assert accel.feeds_into == []
+        assert accel.publishes_to == []
+        assert accel.depends_on == []
+        assert accel.docname == ""
+
+    def test_create_accelerator_complete(self) -> None:
+        """Test creating an accelerator with all fields."""
+        accel = Accelerator(
+            slug="vocabulary",
+            status="alpha",
+            milestone="2 (Nov 2025)",
+            acceptance="Reference environment deployed and accepted.",
+            objective="Accelerate the creation of Sustainable Vocabulary Catalogs.",
+            sources_from=[
+                IntegrationReference(
+                    slug="pilot-data-collection",
+                    description="Scheme documentation, standards materials",
+                ),
+            ],
+            feeds_into=["traceability", "conformity"],
+            publishes_to=[
+                IntegrationReference(
+                    slug="reference-implementation",
+                    description="SVC artefacts",
+                ),
+            ],
+            depends_on=["core-infrastructure"],
+            docname="accelerators/vocabulary",
+        )
+
+        assert accel.slug == "vocabulary"
+        assert accel.status == "alpha"
+        assert accel.milestone == "2 (Nov 2025)"
+        assert len(accel.sources_from) == 1
+        assert accel.sources_from[0].slug == "pilot-data-collection"
+        assert len(accel.feeds_into) == 2
+        assert len(accel.publishes_to) == 1
+
+    def test_empty_slug_raises_error(self) -> None:
+        """Test that empty slug raises validation error."""
+        with pytest.raises(ValidationError, match="slug cannot be empty"):
+            Accelerator(slug="")
+
+    def test_whitespace_slug_raises_error(self) -> None:
+        """Test that whitespace-only slug raises validation error."""
+        with pytest.raises(ValidationError, match="slug cannot be empty"):
+            Accelerator(slug="   ")
+
+    def test_slug_stripped(self) -> None:
+        """Test that slug is stripped of whitespace."""
+        accel = Accelerator(slug="  vocabulary  ")
+        assert accel.slug == "vocabulary"
+
+
+class TestAcceleratorProperties:
+    """Test Accelerator properties."""
+
+    def test_display_title(self) -> None:
+        """Test display_title property."""
+        accel = Accelerator(slug="vocabulary")
+        assert accel.display_title == "Vocabulary"
+
+    def test_display_title_multiple_words(self) -> None:
+        """Test display_title with hyphens."""
+        accel = Accelerator(slug="core-infrastructure")
+        assert accel.display_title == "Core Infrastructure"
+
+    def test_status_normalized(self) -> None:
+        """Test status_normalized property."""
+        accel = Accelerator(slug="test", status="Alpha")
+        assert accel.status_normalized == "alpha"
+
+    def test_status_normalized_empty(self) -> None:
+        """Test status_normalized with empty status."""
+        accel = Accelerator(slug="test")
+        assert accel.status_normalized == ""
+
+
+class TestAcceleratorDependencies:
+    """Test Accelerator dependency methods."""
+
+    @pytest.fixture
+    def sample_accelerator(self) -> Accelerator:
+        """Create a sample accelerator for testing."""
+        return Accelerator(
+            slug="vocabulary",
+            sources_from=[
+                IntegrationReference(slug="pilot-data", description="Pilot data"),
+                IntegrationReference(slug="standards", description="Standards"),
+            ],
+            publishes_to=[
+                IntegrationReference(slug="reference-impl", description="SVC"),
+            ],
+            feeds_into=["traceability", "conformity"],
+            depends_on=["core-infrastructure"],
+        )
+
+    def test_has_integration_dependency_sources(
+        self, sample_accelerator: Accelerator
+    ) -> None:
+        """Test checking sources_from dependency."""
+        assert sample_accelerator.has_integration_dependency("pilot-data") is True
+        assert sample_accelerator.has_integration_dependency("standards") is True
+
+    def test_has_integration_dependency_publishes(
+        self, sample_accelerator: Accelerator
+    ) -> None:
+        """Test checking publishes_to dependency."""
+        assert sample_accelerator.has_integration_dependency("reference-impl") is True
+
+    def test_has_integration_dependency_no_match(
+        self, sample_accelerator: Accelerator
+    ) -> None:
+        """Test checking nonexistent dependency."""
+        assert sample_accelerator.has_integration_dependency("unknown") is False
+
+    def test_has_accelerator_dependency_depends(
+        self, sample_accelerator: Accelerator
+    ) -> None:
+        """Test checking depends_on dependency."""
+        assert (
+            sample_accelerator.has_accelerator_dependency("core-infrastructure") is True
+        )
+
+    def test_has_accelerator_dependency_feeds(
+        self, sample_accelerator: Accelerator
+    ) -> None:
+        """Test checking feeds_into dependency."""
+        assert sample_accelerator.has_accelerator_dependency("traceability") is True
+        assert sample_accelerator.has_accelerator_dependency("conformity") is True
+
+    def test_has_accelerator_dependency_no_match(
+        self, sample_accelerator: Accelerator
+    ) -> None:
+        """Test checking nonexistent accelerator dependency."""
+        assert sample_accelerator.has_accelerator_dependency("unknown") is False
+
+    def test_get_sources_from_slugs(self, sample_accelerator: Accelerator) -> None:
+        """Test getting source integration slugs."""
+        slugs = sample_accelerator.get_sources_from_slugs()
+        assert slugs == ["pilot-data", "standards"]
+
+    def test_get_publishes_to_slugs(self, sample_accelerator: Accelerator) -> None:
+        """Test getting publish integration slugs."""
+        slugs = sample_accelerator.get_publishes_to_slugs()
+        assert slugs == ["reference-impl"]
+
+    def test_get_integration_description_sources(
+        self, sample_accelerator: Accelerator
+    ) -> None:
+        """Test getting description from sources_from."""
+        desc = sample_accelerator.get_integration_description(
+            "pilot-data", "sources_from"
+        )
+        assert desc == "Pilot data"
+
+    def test_get_integration_description_publishes(
+        self, sample_accelerator: Accelerator
+    ) -> None:
+        """Test getting description from publishes_to."""
+        desc = sample_accelerator.get_integration_description(
+            "reference-impl", "publishes_to"
+        )
+        assert desc == "SVC"
+
+    def test_get_integration_description_not_found(
+        self, sample_accelerator: Accelerator
+    ) -> None:
+        """Test getting description for nonexistent integration."""
+        desc = sample_accelerator.get_integration_description("unknown", "sources_from")
+        assert desc is None
+
+
+class TestAcceleratorSerialization:
+    """Test Accelerator serialization."""
+
+    def test_accelerator_to_dict(self) -> None:
+        """Test accelerator can be serialized to dict."""
+        accel = Accelerator(
+            slug="test",
+            status="alpha",
+            sources_from=[IntegrationReference(slug="pilot", description="Data")],
+        )
+
+        data = accel.model_dump()
+        assert data["slug"] == "test"
+        assert data["status"] == "alpha"
+        assert len(data["sources_from"]) == 1
+        assert data["sources_from"][0]["slug"] == "pilot"
+
+    def test_accelerator_to_json(self) -> None:
+        """Test accelerator can be serialized to JSON."""
+        accel = Accelerator(slug="test", status="alpha")
+        json_str = accel.model_dump_json()
+        assert '"slug":"test"' in json_str
+        assert '"status":"alpha"' in json_str