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

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

@@ -0,0 +1,106 @@
+"""JourneyRepository protocol.
+
+Defines the interface for journey data access.
+"""
+
+from typing import Protocol, runtime_checkable
+
+from ..models.journey import Journey
+from .base import BaseRepository
+
+
+@runtime_checkable
+class JourneyRepository(BaseRepository[Journey], Protocol):
+    """Repository protocol for Journey entities.
+
+    Extends BaseRepository with journey-specific query methods.
+    Journeys are defined in RST documents and support incremental builds
+    via docname tracking.
+    """
+
+    async def get_by_persona(self, persona: str) -> list[Journey]:
+        """Get all journeys for a persona.
+
+        Args:
+            persona: Persona name (case-insensitive matching)
+
+        Returns:
+            List of journeys where the persona matches
+        """
+        ...
+
+    async def get_by_docname(self, docname: str) -> list[Journey]:
+        """Get all journeys defined in a specific document.
+
+        Args:
+            docname: RST document name
+
+        Returns:
+            List of journeys from that document
+        """
+        ...
+
+    async def clear_by_docname(self, docname: str) -> int:
+        """Remove all journeys defined in a specific document.
+
+        Used during incremental builds when a document is re-read.
+
+        Args:
+            docname: RST document name
+
+        Returns:
+            Number of journeys removed
+        """
+        ...
+
+    async def get_dependents(self, journey_slug: str) -> list[Journey]:
+        """Get journeys that depend on a specific journey.
+
+        Args:
+            journey_slug: Slug of the journey to find dependents of
+
+        Returns:
+            List of journeys that have this journey in depends_on
+        """
+        ...
+
+    async def get_dependencies(self, journey_slug: str) -> list[Journey]:
+        """Get journeys that a specific journey depends on.
+
+        Args:
+            journey_slug: Slug of the journey to find dependencies of
+
+        Returns:
+            List of journeys that this journey depends on
+        """
+        ...
+
+    async def get_all_personas(self) -> set[str]:
+        """Get all unique personas across all journeys.
+
+        Returns:
+            Set of persona names (normalized)
+        """
+        ...
+
+    async def get_with_story_ref(self, story_title: str) -> list[Journey]:
+        """Get journeys that reference a specific story.
+
+        Args:
+            story_title: Story feature title (case-insensitive)
+
+        Returns:
+            List of journeys containing this story in steps
+        """
+        ...
+
+    async def get_with_epic_ref(self, epic_slug: str) -> list[Journey]:
+        """Get journeys that reference a specific epic.
+
+        Args:
+            epic_slug: Epic slug
+
+        Returns:
+            List of journeys containing this epic in steps
+        """
+        ...

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

@@ -0,0 +1,68 @@
+"""StoryRepository protocol.
+
+Defines the interface for story data access.
+"""
+
+from typing import Protocol, runtime_checkable
+
+from ..models.story import Story
+from .base import BaseRepository
+
+
+@runtime_checkable
+class StoryRepository(BaseRepository[Story], Protocol):
+    """Repository protocol for Story entities.
+
+    Extends BaseRepository with story-specific query methods.
+    Stories are indexed from .feature files and are read-only during
+    a Sphinx build (populated at builder-inited, queried during rendering).
+    """
+
+    async def get_by_app(self, app_slug: str) -> list[Story]:
+        """Get all stories for an application.
+
+        Args:
+            app_slug: Application slug (e.g., "staff-portal")
+
+        Returns:
+            List of stories belonging to the app
+        """
+        ...
+
+    async def get_by_persona(self, persona: str) -> list[Story]:
+        """Get all stories for a persona.
+
+        Args:
+            persona: Persona name (case-insensitive matching)
+
+        Returns:
+            List of stories where the persona matches
+        """
+        ...
+
+    async def get_by_feature_title(self, feature_title: str) -> Story | None:
+        """Get a story by its feature title.
+
+        Args:
+            feature_title: The Feature: line content (case-insensitive)
+
+        Returns:
+            Story if found, None otherwise
+        """
+        ...
+
+    async def get_apps_with_stories(self) -> set[str]:
+        """Get the set of app slugs that have stories.
+
+        Returns:
+            Set of app slugs (normalized)
+        """
+        ...
+
+    async def get_all_personas(self) -> set[str]:
+        """Get all unique personas across all stories.
+
+        Returns:
+            Set of persona names (normalized)
+        """
+        ...

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

@@ -0,0 +1,64 @@
+"""Use cases for sphinx_hcd.
+
+Business logic for cross-referencing and deriving entities.
+"""
+
+from .derive_personas import (
+    derive_personas,
+    derive_personas_by_app_type,
+    get_apps_for_persona,
+    get_epics_for_persona,
+)
+from .resolve_accelerator_references import (
+    get_accelerator_cross_references,
+    get_apps_for_accelerator,
+    get_code_info_for_accelerator,
+    get_dependent_accelerators,
+    get_fed_by_accelerators,
+    get_journeys_for_accelerator,
+    get_publish_integrations,
+    get_source_integrations,
+    get_stories_for_accelerator,
+)
+from .resolve_app_references import (
+    get_app_cross_references,
+    get_epics_for_app,
+    get_journeys_for_app,
+    get_personas_for_app,
+    get_stories_for_app,
+)
+from .resolve_story_references import (
+    get_epics_for_story,
+    get_journeys_for_story,
+    get_related_stories,
+    get_story_cross_references,
+)
+
+__all__ = [
+    # Persona derivation
+    "derive_personas",
+    "derive_personas_by_app_type",
+    "get_apps_for_persona",
+    "get_epics_for_persona",
+    # Story references
+    "get_epics_for_story",
+    "get_journeys_for_story",
+    "get_related_stories",
+    "get_story_cross_references",
+    # App references
+    "get_app_cross_references",
+    "get_epics_for_app",
+    "get_journeys_for_app",
+    "get_personas_for_app",
+    "get_stories_for_app",
+    # Accelerator references
+    "get_accelerator_cross_references",
+    "get_apps_for_accelerator",
+    "get_code_info_for_accelerator",
+    "get_dependent_accelerators",
+    "get_fed_by_accelerators",
+    "get_journeys_for_accelerator",
+    "get_publish_integrations",
+    "get_source_integrations",
+    "get_stories_for_accelerator",
+]

julee/docs/sphinx_hcd/domain/use_cases/derive_personas.py

@@ -0,0 +1,166 @@
+"""Use case for deriving personas from stories and epics.
+
+Personas are not defined directly but are extracted from user stories.
+This use case collects persona information from stories and enriches
+it with epic participation data.
+"""
+
+from collections import defaultdict
+
+from ...utils import normalize_name
+from ..models.app import App
+from ..models.epic import Epic
+from ..models.persona import Persona
+from ..models.story import Story
+
+
+def derive_personas(
+    stories: list[Story],
+    epics: list[Epic],
+) -> list[Persona]:
+    """Derive personas from stories and epics.
+
+    Extracts unique personas from stories, then enriches with:
+    - List of apps each persona uses (from stories)
+    - List of epics each persona participates in (stories in epics)
+
+    Args:
+        stories: List of Story entities
+        epics: List of Epic entities
+
+    Returns:
+        List of Persona entities sorted by name
+    """
+    # Collect persona data from stories
+    persona_data: dict[str, dict] = {}  # normalized_name -> {name, apps}
+
+    for story in stories:
+        normalized = story.persona_normalized
+        if normalized == "unknown":
+            continue
+
+        if normalized not in persona_data:
+            persona_data[normalized] = {
+                "name": story.persona,
+                "apps": set(),
+                "epics": set(),
+            }
+
+        persona_data[normalized]["apps"].add(story.app_slug)
+
+    # Build lookup of normalized story title -> normalized persona
+    story_to_persona: dict[str, str] = {}
+    for story in stories:
+        story_to_persona[normalize_name(story.feature_title)] = story.persona_normalized
+
+    # Find epics for each persona
+    for epic in epics:
+        for story_ref in epic.story_refs:
+            story_normalized = normalize_name(story_ref)
+            persona_normalized = story_to_persona.get(story_normalized)
+            if persona_normalized and persona_normalized in persona_data:
+                persona_data[persona_normalized]["epics"].add(epic.slug)
+
+    # Build Persona entities
+    personas = []
+    for data in persona_data.values():
+        persona = Persona(
+            name=data["name"],
+            app_slugs=sorted(data["apps"]),
+            epic_slugs=sorted(data["epics"]),
+        )
+        personas.append(persona)
+
+    return sorted(personas, key=lambda p: p.name)
+
+
+def derive_personas_by_app_type(
+    stories: list[Story],
+    epics: list[Epic],
+    apps: list[App],
+) -> dict[str, list[Persona]]:
+    """Derive personas grouped by the type of apps they use.
+
+    Args:
+        stories: List of Story entities
+        epics: List of Epic entities
+        apps: List of App entities
+
+    Returns:
+        Dict mapping app type strings to lists of Persona entities
+    """
+    # First derive all personas
+    all_personas = derive_personas(stories, epics)
+
+    # Build app slug -> app type lookup
+    app_types: dict[str, str] = {}
+    for app in apps:
+        app_types[app.slug] = app.app_type.value if app.app_type else "unknown"
+
+    # Group personas by app type
+    personas_by_type: dict[str, list[Persona]] = defaultdict(list)
+
+    for persona in all_personas:
+        # Find all app types this persona uses
+        persona_types: set[str] = set()
+        for app_slug in persona.app_slugs:
+            app_type = app_types.get(app_slug, "unknown")
+            persona_types.add(app_type)
+
+        # Add persona to each type group
+        for app_type in persona_types:
+            personas_by_type[app_type].append(persona)
+
+    # Sort personas within each group
+    return {
+        app_type: sorted(personas, key=lambda p: p.name)
+        for app_type, personas in personas_by_type.items()
+    }
+
+
+def get_epics_for_persona(
+    persona: Persona,
+    epics: list[Epic],
+    stories: list[Story],
+) -> list[Epic]:
+    """Get Epic entities for a persona.
+
+    Args:
+        persona: Persona to get epics for
+        epics: All Epic entities
+        stories: All Story entities
+
+    Returns:
+        List of Epic entities containing stories for this persona
+    """
+    # Build lookup of normalized story title -> normalized persona
+    story_to_persona: dict[str, str] = {}
+    for story in stories:
+        story_to_persona[normalize_name(story.feature_title)] = story.persona_normalized
+
+    matching_epics = []
+    for epic in epics:
+        for story_ref in epic.story_refs:
+            story_normalized = normalize_name(story_ref)
+            if story_to_persona.get(story_normalized) == persona.normalized_name:
+                matching_epics.append(epic)
+                break
+
+    return sorted(matching_epics, key=lambda e: e.slug)
+
+
+def get_apps_for_persona(
+    persona: Persona,
+    apps: list[App],
+) -> list[App]:
+    """Get App entities for a persona.
+
+    Args:
+        persona: Persona to get apps for
+        apps: All App entities
+
+    Returns:
+        List of App entities this persona uses
+    """
+    app_lookup = {app.slug: app for app in apps}
+    return [app_lookup[slug] for slug in persona.app_slugs if slug in app_lookup]

julee/docs/sphinx_hcd/domain/use_cases/resolve_accelerator_references.py

@@ -0,0 +1,236 @@
+"""Use case for resolving accelerator references.
+
+Finds apps, stories, journeys, and integrations related to an accelerator.
+"""
+
+from ...utils import normalize_name
+from ..models.accelerator import Accelerator
+from ..models.app import App
+from ..models.code_info import BoundedContextInfo
+from ..models.integration import Integration
+from ..models.journey import Journey
+from ..models.story import Story
+
+
+def get_apps_for_accelerator(
+    accelerator: Accelerator,
+    apps: list[App],
+) -> list[App]:
+    """Get apps that expose an accelerator.
+
+    Apps expose accelerators via the 'accelerators' field in their manifest.
+
+    Args:
+        accelerator: Accelerator to find apps for
+        apps: All App entities
+
+    Returns:
+        List of App entities that expose this accelerator, sorted by slug
+    """
+    matching = [app for app in apps if accelerator.slug in (app.accelerators or [])]
+    return sorted(matching, key=lambda a: a.slug)
+
+
+def get_stories_for_accelerator(
+    accelerator: Accelerator,
+    apps: list[App],
+    stories: list[Story],
+) -> list[Story]:
+    """Get stories for apps that expose an accelerator.
+
+    Args:
+        accelerator: Accelerator to find stories for
+        apps: All App entities
+        stories: All Story entities
+
+    Returns:
+        List of Story entities from apps that expose this accelerator
+    """
+    # Get app slugs that expose this accelerator
+    app_slugs = {
+        app.slug for app in apps if accelerator.slug in (app.accelerators or [])
+    }
+
+    if not app_slugs:
+        return []
+
+    # Find stories for those apps
+    matching = [s for s in stories if s.app_slug in app_slugs]
+    return sorted(matching, key=lambda s: s.feature_title)
+
+
+def get_journeys_for_accelerator(
+    accelerator: Accelerator,
+    apps: list[App],
+    stories: list[Story],
+    journeys: list[Journey],
+) -> list[Journey]:
+    """Get journeys that include stories from an accelerator's apps.
+
+    Args:
+        accelerator: Accelerator to find journeys for
+        apps: All App entities
+        stories: All Story entities
+        journeys: All Journey entities
+
+    Returns:
+        List of Journey entities containing stories from this accelerator's apps
+    """
+    # Get stories for this accelerator
+    accel_stories = get_stories_for_accelerator(accelerator, apps, stories)
+    story_titles = {normalize_name(s.feature_title) for s in accel_stories}
+
+    if not story_titles:
+        return []
+
+    # Find journeys containing these stories
+    matching = []
+    for journey in journeys:
+        story_refs = journey.get_story_refs()
+        if any(normalize_name(ref) in story_titles for ref in story_refs):
+            matching.append(journey)
+
+    return sorted(matching, key=lambda j: j.slug)
+
+
+def get_source_integrations(
+    accelerator: Accelerator,
+    integrations: list[Integration],
+) -> list[Integration]:
+    """Get integrations that an accelerator sources from.
+
+    Args:
+        accelerator: Accelerator to find sources for
+        integrations: All Integration entities
+
+    Returns:
+        List of Integration entities this accelerator sources from
+    """
+    source_slugs = accelerator.get_sources_from_slugs()
+    integration_lookup = {i.slug: i for i in integrations}
+
+    return [
+        integration_lookup[slug] for slug in source_slugs if slug in integration_lookup
+    ]
+
+
+def get_publish_integrations(
+    accelerator: Accelerator,
+    integrations: list[Integration],
+) -> list[Integration]:
+    """Get integrations that an accelerator publishes to.
+
+    Args:
+        accelerator: Accelerator to find publish targets for
+        integrations: All Integration entities
+
+    Returns:
+        List of Integration entities this accelerator publishes to
+    """
+    publish_slugs = accelerator.get_publishes_to_slugs()
+    integration_lookup = {i.slug: i for i in integrations}
+
+    return [
+        integration_lookup[slug] for slug in publish_slugs if slug in integration_lookup
+    ]
+
+
+def get_dependent_accelerators(
+    accelerator: Accelerator,
+    accelerators: list[Accelerator],
+) -> list[Accelerator]:
+    """Get accelerators that depend on a specific accelerator.
+
+    Args:
+        accelerator: Accelerator to find dependents of
+        accelerators: All Accelerator entities
+
+    Returns:
+        List of Accelerator entities that depend on this one
+    """
+    matching = [a for a in accelerators if accelerator.slug in a.depends_on]
+    return sorted(matching, key=lambda a: a.slug)
+
+
+def get_fed_by_accelerators(
+    accelerator: Accelerator,
+    accelerators: list[Accelerator],
+) -> list[Accelerator]:
+    """Get accelerators that feed into a specific accelerator.
+
+    Args:
+        accelerator: Accelerator to find feeders for
+        accelerators: All Accelerator entities
+
+    Returns:
+        List of Accelerator entities that feed into this one
+    """
+    matching = [a for a in accelerators if accelerator.slug in a.feeds_into]
+    return sorted(matching, key=lambda a: a.slug)
+
+
+def get_code_info_for_accelerator(
+    accelerator: Accelerator,
+    code_infos: list[BoundedContextInfo],
+) -> BoundedContextInfo | None:
+    """Get code info for an accelerator's bounded context.
+
+    Tries to match by slug or snake_case version of slug.
+
+    Args:
+        accelerator: Accelerator to find code for
+        code_infos: All BoundedContextInfo entities
+
+    Returns:
+        BoundedContextInfo if found, None otherwise
+    """
+    # Try exact match
+    for info in code_infos:
+        if info.slug == accelerator.slug:
+            return info
+
+    # Try snake_case match
+    snake_slug = accelerator.slug.replace("-", "_")
+    for info in code_infos:
+        if info.slug == snake_slug or info.code_dir == snake_slug:
+            return info
+
+    return None
+
+
+def get_accelerator_cross_references(
+    accelerator: Accelerator,
+    accelerators: list[Accelerator],
+    apps: list[App],
+    stories: list[Story],
+    journeys: list[Journey],
+    integrations: list[Integration],
+    code_infos: list[BoundedContextInfo],
+) -> dict:
+    """Get all cross-references for an accelerator.
+
+    Convenience function to get all related entities at once.
+
+    Args:
+        accelerator: Accelerator to find references for
+        accelerators: All Accelerator entities
+        apps: All App entities
+        stories: All Story entities
+        journeys: All Journey entities
+        integrations: All Integration entities
+        code_infos: All BoundedContextInfo entities
+
+    Returns:
+        Dict with keys: apps, stories, journeys, source_integrations,
+                       publish_integrations, dependents, fed_by, code_info
+    """
+    return {
+        "apps": get_apps_for_accelerator(accelerator, apps),
+        "stories": get_stories_for_accelerator(accelerator, apps, stories),
+        "journeys": get_journeys_for_accelerator(accelerator, apps, stories, journeys),
+        "source_integrations": get_source_integrations(accelerator, integrations),
+        "publish_integrations": get_publish_integrations(accelerator, integrations),
+        "dependents": get_dependent_accelerators(accelerator, accelerators),
+        "fed_by": get_fed_by_accelerators(accelerator, accelerators),
+        "code_info": get_code_info_for_accelerator(accelerator, code_infos),
+    }