julee-viewpoints 0.1.0__py3-none-any.whl

julee_viewpoints/__init__.py

@@ -0,0 +1,26 @@
+"""Code-outward documentation for julee solutions.
+
+This kit projects a solution into documentation: its personas, journeys,
+epics and stories, its applications and integrations, and the bounded
+contexts its code already describes (ADR 006).
+
+It is a viewpoint kit. Its bounded contexts describe a solution rather
+than implement part of one, which is why the manifest sets
+``viewpoint=True``.
+
+Use it in a solution's ``conf.py``::
+
+    extensions = ["julee_viewpoints.sphinx_hcd"]
+"""
+
+from julee.core.entities.kit import Kit
+
+kit = Kit(
+    slug="viewpoints",
+    name="Code-outward documentation",
+    package="julee_viewpoints",
+    viewpoint=True,
+    contributes={"sphinx.extension": "julee_viewpoints.sphinx_hcd"},
+)
+
+__all__ = ["kit"]

julee_viewpoints/sphinx_hcd/__init__.py

@@ -0,0 +1,209 @@
+"""Sphinx HCD (Human-Centered Design) Extensions for Julee Solutions.
+
+This package provides Sphinx extensions for documenting Julee-based solutions
+using Human-Centered Design patterns. It supports:
+
+- Stories: User stories derived from Gherkin .feature files
+- Journeys: User journeys composed of stories and epics
+- Epics: Collections of related stories
+- Apps: Application documentation with manifest-based metadata
+- Accelerators: Domain accelerator documentation with bounded context scanning
+- Integrations: External integration documentation
+- Personas: Auto-generated UML diagrams showing persona-epic-app relationships
+
+Usage in conf.py::
+
+    extensions = ["julee_viewpoints.sphinx_hcd"]
+
+    # Optional configuration (defaults match standard Julee layout)
+    sphinx_hcd = {
+        'paths': {
+            'feature_files': 'tests/e2e/',
+            'app_manifests': 'apps/',
+            'integration_manifests': 'src/integrations/',
+            'bounded_contexts': 'src/',
+        },
+        'docs_structure': {
+            'applications': 'applications',
+            'personas': 'users/personas',
+            'journeys': 'users/journeys',
+            'epics': 'users/epics',
+            'accelerators': 'domain/accelerators',
+            'integrations': 'integrations',
+            'stories': 'users/stories',
+        },
+    }
+"""
+
+from sphinx.util import logging
+
+from .config import init_config
+
+logger = logging.getLogger(__name__)
+
+
+def setup(app):
+    """Set up all HCD extensions for Sphinx."""
+    from .sphinx.directives import (
+        AcceleratorDependencyDiagramDirective,
+        AcceleratorDependencyDiagramPlaceholder,
+        AcceleratorIndexDirective,
+        AcceleratorIndexPlaceholder,
+        AcceleratorsForAppDirective,
+        AcceleratorsForAppPlaceholder,
+        AcceleratorStatusDirective,
+        AppIndexDirective,
+        AppIndexPlaceholder,
+        AppsForPersonaDirective,
+        AppsForPersonaPlaceholder,
+        # Accelerator directives
+        DefineAcceleratorDirective,
+        DefineAcceleratorPlaceholder,
+        # App directives
+        DefineAppDirective,
+        DefineAppPlaceholder,
+        # Epic directives
+        DefineEpicDirective,
+        # Integration directives
+        DefineIntegrationDirective,
+        DefineIntegrationPlaceholder,
+        # Journey directives
+        DefineJourneyDirective,
+        DependentAcceleratorsDirective,
+        DependentAcceleratorsPlaceholder,
+        EpicIndexDirective,
+        EpicIndexPlaceholder,
+        EpicsForPersonaDirective,
+        EpicsForPersonaPlaceholder,
+        EpicStoryDirective,
+        GherkinAppStoriesDirective,
+        GherkinStoriesDirective,
+        GherkinStoriesForAppDirective,
+        GherkinStoriesForPersonaDirective,
+        GherkinStoriesIndexDirective,
+        # Story deprecated aliases
+        GherkinStoryDirective,
+        IntegrationIndexDirective,
+        IntegrationIndexPlaceholder,
+        JourneyDependencyGraphDirective,
+        JourneyDependencyGraphPlaceholder,
+        JourneyIndexDirective,
+        JourneysForPersonaDirective,
+        # Persona directives
+        PersonaDiagramDirective,
+        PersonaDiagramPlaceholder,
+        PersonaIndexDiagramDirective,
+        PersonaIndexDiagramPlaceholder,
+        StepEpicDirective,
+        StepPhaseDirective,
+        StepStoryDirective,
+        StoriesDirective,
+        # Story directives
+        StoryAppDirective,
+        StoryIndexDirective,
+        StoryListForAppDirective,
+        StoryListForPersonaDirective,
+        StoryRefDirective,
+        StorySeeAlsoPlaceholder,
+    )
+    from .sphinx.event_handlers import (
+        on_builder_inited,
+        on_doctree_read,
+        on_doctree_resolved,
+        on_env_purge_doc,
+    )
+
+    # Register configuration value first
+    app.add_config_value("sphinx_hcd", {}, "env")
+
+    # Initialize config when builder starts (after conf.py is loaded)
+    app.connect("builder-inited", _init_config_handler, priority=0)
+
+    # Connect event handlers
+    app.connect("builder-inited", on_builder_inited, priority=100)
+    app.connect("doctree-read", on_doctree_read)
+    app.connect("doctree-resolved", on_doctree_resolved)
+    app.connect("env-purge-doc", on_env_purge_doc)
+
+    # Register story directives
+    app.add_directive("story", StoryRefDirective)
+    app.add_directive("stories", StoriesDirective)
+    app.add_directive("story-list-for-persona", StoryListForPersonaDirective)
+    app.add_directive("story-list-for-app", StoryListForAppDirective)
+    app.add_directive("story-index", StoryIndexDirective)
+    app.add_directive("story-app", StoryAppDirective)
+    app.add_node(StorySeeAlsoPlaceholder)
+
+    # Register deprecated story aliases
+    app.add_directive("gherkin-story", GherkinStoryDirective)
+    app.add_directive("gherkin-stories", GherkinStoriesDirective)
+    app.add_directive("gherkin-stories-for-persona", GherkinStoriesForPersonaDirective)
+    app.add_directive("gherkin-stories-for-app", GherkinStoriesForAppDirective)
+    app.add_directive("gherkin-stories-index", GherkinStoriesIndexDirective)
+    app.add_directive("gherkin-app-stories", GherkinAppStoriesDirective)
+
+    # Register journey directives
+    app.add_directive("define-journey", DefineJourneyDirective)
+    app.add_directive("step-story", StepStoryDirective)
+    app.add_directive("step-epic", StepEpicDirective)
+    app.add_directive("step-phase", StepPhaseDirective)
+    app.add_directive("journey-index", JourneyIndexDirective)
+    app.add_directive("journey-dependency-graph", JourneyDependencyGraphDirective)
+    app.add_directive("journeys-for-persona", JourneysForPersonaDirective)
+    app.add_node(JourneyDependencyGraphPlaceholder)
+
+    # Register epic directives
+    app.add_directive("define-epic", DefineEpicDirective)
+    app.add_directive("epic-story", EpicStoryDirective)
+    app.add_directive("epic-index", EpicIndexDirective)
+    app.add_directive("epics-for-persona", EpicsForPersonaDirective)
+    app.add_node(EpicIndexPlaceholder)
+    app.add_node(EpicsForPersonaPlaceholder)
+
+    # Register app directives
+    app.add_directive("define-app", DefineAppDirective)
+    app.add_directive("app-index", AppIndexDirective)
+    app.add_directive("apps-for-persona", AppsForPersonaDirective)
+    app.add_node(DefineAppPlaceholder)
+    app.add_node(AppIndexPlaceholder)
+    app.add_node(AppsForPersonaPlaceholder)
+
+    # Register accelerator directives
+    app.add_directive("define-accelerator", DefineAcceleratorDirective)
+    app.add_directive("accelerator-index", AcceleratorIndexDirective)
+    app.add_directive("accelerators-for-app", AcceleratorsForAppDirective)
+    app.add_directive("dependent-accelerators", DependentAcceleratorsDirective)
+    app.add_directive(
+        "accelerator-dependency-diagram", AcceleratorDependencyDiagramDirective
+    )
+    app.add_directive("accelerator-status", AcceleratorStatusDirective)
+    app.add_node(DefineAcceleratorPlaceholder)
+    app.add_node(AcceleratorIndexPlaceholder)
+    app.add_node(AcceleratorsForAppPlaceholder)
+    app.add_node(DependentAcceleratorsPlaceholder)
+    app.add_node(AcceleratorDependencyDiagramPlaceholder)
+
+    # Register integration directives
+    app.add_directive("define-integration", DefineIntegrationDirective)
+    app.add_directive("integration-index", IntegrationIndexDirective)
+    app.add_node(DefineIntegrationPlaceholder)
+    app.add_node(IntegrationIndexPlaceholder)
+
+    # Register persona directives
+    app.add_directive("persona-diagram", PersonaDiagramDirective)
+    app.add_directive("persona-index-diagram", PersonaIndexDiagramDirective)
+    app.add_node(PersonaDiagramPlaceholder)
+    app.add_node(PersonaIndexDiagramPlaceholder)
+
+    logger.info("Loaded julee_viewpoints.sphinx_hcd extensions")
+
+    return {
+        "version": "2.0",
+        "parallel_read_safe": False,
+        "parallel_write_safe": True,
+    }
+
+
+def _init_config_handler(app):
+    """Initialize HCD config from Sphinx app config."""
+    init_config(app)

julee_viewpoints/sphinx_hcd/config.py

@@ -0,0 +1,149 @@
+"""Configuration for sphinx_hcd extension.
+
+Provides defaults matching the RBA solution layout, with ability to override
+via sphinx_hcd config dict in conf.py.
+"""
+
+from copy import deepcopy
+from pathlib import Path
+
+DEFAULT_CONFIG = {
+    "paths": {
+        # Where to find Gherkin feature files: {app}/features/*.feature
+        "feature_files": "tests/e2e/",
+        # Where to find app manifests: */app.yaml
+        "app_manifests": "apps/",
+        # Where to find integration manifests: */integration.yaml
+        "integration_manifests": "src/integrations/",
+        # Where to find bounded context code: {slug}/ directories
+        "bounded_contexts": "src/",
+    },
+    "docs_structure": {
+        # RST file locations relative to docs root
+        "applications": "applications",
+        "personas": "users/personas",
+        "journeys": "users/journeys",
+        "epics": "users/epics",
+        "accelerators": "domain/accelerators",
+        "integrations": "integrations",
+        "stories": "users/stories",
+    },
+}
+
+
+def config_factory() -> dict:
+    """Return a fresh config dict populated with defaults.
+
+    Usage in conf.py::
+
+        from julee_viewpoints.sphinx_hcd import config_factory
+
+        sphinx_hcd = config_factory()
+        sphinx_hcd['paths']['feature_files'] = 'tests/bdd/'
+
+    Returns:
+        A deep copy of DEFAULT_CONFIG that can be modified.
+    """
+    return deepcopy(DEFAULT_CONFIG)
+
+
+def _deep_merge(base: dict, override: dict) -> dict:
+    """Deep merge override into base, returning new dict."""
+    result = deepcopy(base)
+    for key, value in override.items():
+        if key in result and isinstance(result[key], dict) and isinstance(value, dict):
+            result[key] = _deep_merge(result[key], value)
+        else:
+            result[key] = deepcopy(value)
+    return result
+
+
+class HCDConfig:
+    """Configuration holder for sphinx_hcd extension.
+
+    Provides access to paths and doc structure settings, resolving paths
+    relative to the project root.
+    """
+
+    def __init__(self, app):
+        """Initialize config from Sphinx app.
+
+        Args:
+            app: Sphinx application instance
+        """
+        self._app = app
+        self._docs_dir = Path(app.srcdir)
+        self._project_root = self._docs_dir.parent
+
+        # Merge user config with defaults
+        user_config = getattr(app.config, "sphinx_hcd", {}) or {}
+        self._config = _deep_merge(DEFAULT_CONFIG, user_config)
+
+    @property
+    def project_root(self) -> Path:
+        """Project root directory (parent of docs/)."""
+        return self._project_root
+
+    @property
+    def docs_dir(self) -> Path:
+        """Documentation source directory."""
+        return self._docs_dir
+
+    def get_path(self, key: str) -> Path:
+        """Get an absolute path from the paths config.
+
+        Args:
+            key: Path key (e.g., 'feature_files', 'app_manifests')
+
+        Returns:
+            Absolute Path resolved relative to project root
+        """
+        rel_path: str = self._config["paths"].get(key, "")
+        return self._project_root / rel_path
+
+    def get_doc_path(self, key: str) -> str:
+        """Get a doc structure path.
+
+        Args:
+            key: Doc path key (e.g., 'applications', 'personas')
+
+        Returns:
+            Relative path string for use in doc references
+        """
+        doc_path: str = self._config["docs_structure"].get(key, key)
+        return doc_path
+
+
+# Module-level config instance, set by setup()
+_config: HCDConfig | None = None
+
+
+def get_config() -> HCDConfig:
+    """Get the current HCD configuration.
+
+    Returns:
+        HCDConfig instance
+
+    Raises:
+        RuntimeError: If called before extension is initialized
+    """
+    if _config is None:
+        raise RuntimeError(
+            "sphinx_hcd config not initialized. "
+            "Ensure 'julee_viewpoints.sphinx_hcd' is in your Sphinx extensions."
+        )
+    return _config
+
+
+def init_config(app) -> HCDConfig:
+    """Initialize config from Sphinx app. Called by extension setup.
+
+    Args:
+        app: Sphinx application instance
+
+    Returns:
+        HCDConfig instance
+    """
+    global _config
+    _config = HCDConfig(app)
+    return _config

julee_viewpoints/sphinx_hcd/domain/__init__.py

@@ -0,0 +1,5 @@
+"""Domain layer for sphinx_hcd.
+
+Contains domain models, repository protocols, and use cases following
+julee clean architecture patterns.
+"""

julee_viewpoints/sphinx_hcd/domain/models/__init__.py

@@ -0,0 +1,32 @@
+"""Domain models for sphinx_hcd.
+
+Pydantic models representing HCD entities: stories, journeys, epics,
+apps, accelerators, integrations, and personas.
+"""
+
+from .accelerator import Accelerator, IntegrationReference
+from .app import App, AppType
+from .code_info import BoundedContextInfo, ClassInfo
+from .epic import Epic
+from .integration import Direction, ExternalDependency, Integration
+from .journey import Journey, JourneyStep, StepType
+from .persona import Persona
+from .story import Story
+
+__all__ = [
+    "Accelerator",
+    "App",
+    "AppType",
+    "BoundedContextInfo",
+    "ClassInfo",
+    "Direction",
+    "Epic",
+    "ExternalDependency",
+    "Integration",
+    "IntegrationReference",
+    "Journey",
+    "JourneyStep",
+    "Persona",
+    "StepType",
+    "Story",
+]

julee_viewpoints/sphinx_hcd/domain/models/accelerator.py

@@ -0,0 +1,158 @@
+"""Accelerator domain model.
+
+Represents an accelerator (bounded context) in the HCD documentation system.
+Accelerators are defined via RST directives and may have associated code.
+"""
+
+from pydantic import Field, field_validator
+
+from julee.core.entities.entity import Entity
+
+
+class IntegrationReference(Entity):
+    """Reference to an integration with optional description.
+
+    Used for sources_from and publishes_to relationships where
+    an accelerator may specify what data it sources or publishes.
+    """
+
+    slug: str = Field(description='Integration slug (e.g., "pilot-data-collection")')
+    description: str = Field(
+        default="",
+        description='What is sourced/published (e.g., "Scheme documentation")',
+    )
+
+    @field_validator("slug", mode="before")
+    @classmethod
+    def validate_slug(cls, v: str) -> str:
+        """Validate slug is not empty."""
+        if not v or not v.strip():
+            raise ValueError("slug cannot be empty")
+        return v.strip()
+
+    @classmethod
+    def from_dict(cls, data: dict | str) -> "IntegrationReference":
+        """Create from dict or string.
+
+        Args:
+            data: Either a dict with slug/description or a plain string slug
+
+        Returns:
+            IntegrationReference instance
+        """
+        if isinstance(data, str):
+            return cls(slug=data)
+        return cls(slug=data.get("slug", ""), description=data.get("description", ""))
+
+
+class Accelerator(Entity):
+    """Accelerator entity.
+
+    An accelerator represents a bounded context that provides business
+    capabilities. It may have associated code in src/{slug}/ and is
+    exposed through one or more applications.
+    """
+
+    slug: str = Field(description='URL-safe identifier (e.g., "vocabulary")')
+    status: str = Field(
+        default="",
+        description='Development status (e.g., "alpha", "production", "future")',
+    )
+    milestone: str | None = Field(
+        default=None, description='Target milestone (e.g., "2 (Nov 2025)")'
+    )
+    acceptance: str | None = Field(
+        default=None, description="Acceptance criteria description"
+    )
+    objective: str = Field(default="", description="Business objective/description")
+    sources_from: tuple[IntegrationReference, ...] = Field(
+        default_factory=tuple, description="Integrations this accelerator reads from"
+    )
+    feeds_into: tuple[str, ...] = Field(
+        default_factory=tuple, description="Other accelerators this one feeds data into"
+    )
+    publishes_to: tuple[IntegrationReference, ...] = Field(
+        default_factory=tuple, description="Integrations this accelerator writes to"
+    )
+    depends_on: tuple[str, ...] = Field(
+        default_factory=tuple, description="Other accelerators this one depends on"
+    )
+    docname: str = Field(
+        default="", description="RST document name (for incremental builds)"
+    )
+
+    @field_validator("slug", mode="before")
+    @classmethod
+    def validate_slug(cls, v: str) -> str:
+        """Validate slug is not empty."""
+        if not v or not v.strip():
+            raise ValueError("slug cannot be empty")
+        return v.strip()
+
+    @property
+    def display_title(self) -> str:
+        """Get formatted title for display."""
+        return self.slug.replace("-", " ").title()
+
+    @property
+    def status_normalized(self) -> str:
+        """Get normalized status for grouping."""
+        return self.status.lower().strip() if self.status else ""
+
+    def has_integration_dependency(self, integration_slug: str) -> bool:
+        """Check if accelerator depends on an integration.
+
+        Args:
+            integration_slug: Integration slug to check
+
+        Returns:
+            True if sources_from or publishes_to contains this integration
+        """
+        for ref in self.sources_from:
+            if ref.slug == integration_slug:
+                return True
+        for ref in self.publishes_to:
+            if ref.slug == integration_slug:
+                return True
+        return False
+
+    def has_accelerator_dependency(self, accelerator_slug: str) -> bool:
+        """Check if accelerator depends on another accelerator.
+
+        Args:
+            accelerator_slug: Accelerator slug to check
+
+        Returns:
+            True if depends_on or feeds_into contains this accelerator
+        """
+        return (
+            accelerator_slug in self.depends_on or accelerator_slug in self.feeds_into
+        )
+
+    def get_sources_from_slugs(self) -> list[str]:
+        """Get list of integration slugs this accelerator sources from."""
+        return [ref.slug for ref in self.sources_from]
+
+    def get_publishes_to_slugs(self) -> list[str]:
+        """Get list of integration slugs this accelerator publishes to."""
+        return [ref.slug for ref in self.publishes_to]
+
+    def get_integration_description(
+        self, integration_slug: str, relationship: str
+    ) -> str | None:
+        """Get description for an integration relationship.
+
+        Args:
+            integration_slug: Integration to look up
+            relationship: Either "sources_from" or "publishes_to"
+
+        Returns:
+            Description if found, None otherwise
+        """
+        refs = (
+            self.sources_from if relationship == "sources_from" else self.publishes_to
+        )
+        for ref in refs:
+            if ref.slug == integration_slug:
+                return ref.description or None
+        return None