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

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

@@ -0,0 +1,230 @@
+"""Integration domain model.
+
+Represents an integration module in the HCD documentation system.
+Integrations are defined via YAML manifests in integrations/*/integration.yaml.
+"""
+
+from enum import Enum
+
+from pydantic import BaseModel, Field, field_validator
+
+from ...utils import normalize_name
+
+
+class Direction(str, Enum):
+    """Integration data flow direction."""
+
+    INBOUND = "inbound"
+    OUTBOUND = "outbound"
+    BIDIRECTIONAL = "bidirectional"
+
+    @classmethod
+    def from_string(cls, value: str) -> "Direction":
+        """Convert string to Direction, defaulting to BIDIRECTIONAL."""
+        try:
+            return cls(value.lower())
+        except ValueError:
+            return cls.BIDIRECTIONAL
+
+    @property
+    def label(self) -> str:
+        """Get human-readable label."""
+        labels = {
+            Direction.INBOUND: "Inbound (data source)",
+            Direction.OUTBOUND: "Outbound (data sink)",
+            Direction.BIDIRECTIONAL: "Bidirectional",
+        }
+        return labels.get(self, str(self.value))
+
+
+class ExternalDependency(BaseModel):
+    """External system that an integration depends on.
+
+    Attributes:
+        name: Display name of the external system
+        url: Optional URL for documentation or reference
+        description: Optional brief description
+    """
+
+    name: str
+    url: str | None = None
+    description: str = ""
+
+    @field_validator("name", mode="before")
+    @classmethod
+    def validate_name(cls, v: str) -> str:
+        """Validate name is not empty."""
+        if not v or not v.strip():
+            raise ValueError("name cannot be empty")
+        return v.strip()
+
+    @classmethod
+    def from_dict(cls, data: dict) -> "ExternalDependency":
+        """Create from dictionary (YAML parsed data).
+
+        Args:
+            data: Dictionary with name, url, description keys
+
+        Returns:
+            ExternalDependency instance
+        """
+        return cls(
+            name=data.get("name", ""),
+            url=data.get("url"),
+            description=data.get("description", ""),
+        )
+
+
+class Integration(BaseModel):
+    """Integration module entity.
+
+    Integrations represent connections to external systems, defining
+    data flow direction and external dependencies.
+
+    Attributes:
+        slug: URL-safe identifier (e.g., "pilot-data-collection")
+        module: Python module name (e.g., "pilot_data_collection")
+        name: Display name
+        description: Human-readable description
+        direction: Data flow direction
+        depends_on: List of external dependencies
+        manifest_path: Path to the integration.yaml file
+        name_normalized: Lowercase name for matching
+    """
+
+    slug: str
+    module: str
+    name: str
+    description: str = ""
+    direction: Direction = Direction.BIDIRECTIONAL
+    depends_on: list[ExternalDependency] = Field(default_factory=list)
+    manifest_path: str = ""
+    name_normalized: str = ""
+
+    @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()
+
+    @field_validator("module", mode="before")
+    @classmethod
+    def validate_module(cls, v: str) -> str:
+        """Validate module is not empty."""
+        if not v or not v.strip():
+            raise ValueError("module cannot be empty")
+        return v.strip()
+
+    @field_validator("name", mode="before")
+    @classmethod
+    def validate_name(cls, v: str) -> str:
+        """Validate name is not empty."""
+        if not v or not v.strip():
+            raise ValueError("name cannot be empty")
+        return v.strip()
+
+    @field_validator("name_normalized", mode="before")
+    @classmethod
+    def compute_name_normalized(cls, v: str, info) -> str:
+        """Compute normalized name from name if not provided."""
+        if v:
+            return v
+        name = info.data.get("name", "")
+        return normalize_name(name) if name else ""
+
+    def model_post_init(self, __context) -> None:
+        """Ensure normalized fields are computed after init."""
+        if not self.name_normalized and self.name:
+            object.__setattr__(self, "name_normalized", normalize_name(self.name))
+
+    @classmethod
+    def from_manifest(
+        cls,
+        module_name: str,
+        manifest: dict,
+        manifest_path: str,
+    ) -> "Integration":
+        """Create an Integration from a parsed YAML manifest.
+
+        Args:
+            module_name: Module directory name
+            manifest: Parsed YAML content
+            manifest_path: Path to the manifest file
+
+        Returns:
+            Integration instance
+        """
+        slug = manifest.get("slug", module_name.replace("_", "-"))
+        name = manifest.get("name", slug.replace("-", " ").title())
+        direction = Direction.from_string(manifest.get("direction", "bidirectional"))
+
+        # Parse depends_on list
+        depends_on_raw = manifest.get("depends_on", [])
+        depends_on = [
+            (
+                ExternalDependency.from_dict(dep)
+                if isinstance(dep, dict)
+                else ExternalDependency(name=str(dep))
+            )
+            for dep in depends_on_raw
+        ]
+
+        return cls(
+            slug=slug,
+            module=module_name,
+            name=name,
+            description=manifest.get("description", "").strip(),
+            direction=direction,
+            depends_on=depends_on,
+            manifest_path=manifest_path,
+        )
+
+    def matches_direction(self, direction: Direction | str) -> bool:
+        """Check if this integration matches the given direction.
+
+        Args:
+            direction: Direction enum or string to match
+
+        Returns:
+            True if integration matches the direction
+        """
+        if isinstance(direction, str):
+            direction = Direction.from_string(direction)
+        return self.direction == direction
+
+    def matches_name(self, name: str) -> bool:
+        """Check if this integration matches the given name (case-insensitive).
+
+        Args:
+            name: Name to match against
+
+        Returns:
+            True if normalized names match
+        """
+        return self.name_normalized == normalize_name(name)
+
+    def has_dependency(self, dep_name: str) -> bool:
+        """Check if this integration has a specific dependency.
+
+        Args:
+            dep_name: Dependency name to check (case-insensitive)
+
+        Returns:
+            True if dependency exists
+        """
+        dep_normalized = normalize_name(dep_name)
+        return any(
+            normalize_name(dep.name) == dep_normalized for dep in self.depends_on
+        )
+
+    @property
+    def direction_label(self) -> str:
+        """Get human-readable direction label."""
+        return self.direction.label
+
+    @property
+    def module_path(self) -> str:
+        """Get full module path for display."""
+        return f"integrations.{self.module}"

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

@@ -0,0 +1,222 @@
+"""Journey domain model.
+
+Represents a user journey in the HCD documentation system.
+Journeys are defined via RST directives and track a persona's path
+through the system to achieve a goal.
+"""
+
+from enum import Enum
+
+from pydantic import BaseModel, Field, field_validator
+
+from ...utils import normalize_name
+
+
+class StepType(str, Enum):
+    """Type of journey step."""
+
+    STORY = "story"
+    EPIC = "epic"
+    PHASE = "phase"
+
+    @classmethod
+    def from_string(cls, value: str) -> "StepType":
+        """Convert string to StepType."""
+        try:
+            return cls(value.lower())
+        except ValueError:
+            raise ValueError(f"Invalid step type: {value}")
+
+
+class JourneyStep(BaseModel):
+    """A step within a journey.
+
+    Steps can be stories (feature references), epics (epic references),
+    or phases (grouping labels for subsequent steps).
+
+    Attributes:
+        step_type: The type of step (story, epic, phase)
+        ref: Reference identifier (story title, epic slug, or phase title)
+        description: Optional description (primarily for phases)
+    """
+
+    step_type: StepType
+    ref: str
+    description: str = ""
+
+    @field_validator("ref", mode="before")
+    @classmethod
+    def validate_ref(cls, v: str) -> str:
+        """Validate ref is not empty."""
+        if not v or not v.strip():
+            raise ValueError("ref cannot be empty")
+        return v.strip()
+
+    @classmethod
+    def story(cls, title: str) -> "JourneyStep":
+        """Create a story step.
+
+        Args:
+            title: Story feature title
+
+        Returns:
+            JourneyStep with type STORY
+        """
+        return cls(step_type=StepType.STORY, ref=title)
+
+    @classmethod
+    def epic(cls, slug: str) -> "JourneyStep":
+        """Create an epic step.
+
+        Args:
+            slug: Epic slug
+
+        Returns:
+            JourneyStep with type EPIC
+        """
+        return cls(step_type=StepType.EPIC, ref=slug)
+
+    @classmethod
+    def phase(cls, title: str, description: str = "") -> "JourneyStep":
+        """Create a phase step.
+
+        Args:
+            title: Phase title
+            description: Optional phase description
+
+        Returns:
+            JourneyStep with type PHASE
+        """
+        return cls(step_type=StepType.PHASE, ref=title, description=description)
+
+    @property
+    def is_story(self) -> bool:
+        """Check if this is a story step."""
+        return self.step_type == StepType.STORY
+
+    @property
+    def is_epic(self) -> bool:
+        """Check if this is an epic step."""
+        return self.step_type == StepType.EPIC
+
+    @property
+    def is_phase(self) -> bool:
+        """Check if this is a phase step."""
+        return self.step_type == StepType.PHASE
+
+
+class Journey(BaseModel):
+    """User journey entity.
+
+    A journey represents a persona's path through the system to achieve
+    a goal. It captures the user's motivation, the value delivered, and
+    the sequence of steps they follow.
+
+    Attributes:
+        slug: URL-safe identifier (e.g., "build-vocabulary")
+        persona: The persona undertaking this journey
+        persona_normalized: Lowercase persona for matching
+        intent: What the persona wants (their motivation)
+        outcome: What success looks like (business value)
+        goal: Activity description (what they do)
+        depends_on: Journey slugs that must be completed first
+        steps: Sequence of journey steps
+        preconditions: Conditions that must be true before starting
+        postconditions: Conditions that will be true after completion
+        docname: RST document name (for incremental builds)
+    """
+
+    slug: str
+    persona: str = ""
+    persona_normalized: str = ""
+    intent: str = ""
+    outcome: str = ""
+    goal: str = ""
+    depends_on: list[str] = Field(default_factory=list)
+    steps: list[JourneyStep] = Field(default_factory=list)
+    preconditions: list[str] = Field(default_factory=list)
+    postconditions: list[str] = Field(default_factory=list)
+    docname: str = ""
+
+    @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()
+
+    @field_validator("persona_normalized", mode="before")
+    @classmethod
+    def compute_persona_normalized(cls, v: str, info) -> str:
+        """Compute normalized persona from persona if not provided."""
+        if v:
+            return v
+        persona = info.data.get("persona", "")
+        return normalize_name(persona) if persona else ""
+
+    def model_post_init(self, __context) -> None:
+        """Ensure normalized fields are computed after init."""
+        if not self.persona_normalized and self.persona:
+            object.__setattr__(self, "persona_normalized", normalize_name(self.persona))
+
+    def matches_persona(self, persona_name: str) -> bool:
+        """Check if this journey matches the given persona (case-insensitive).
+
+        Args:
+            persona_name: Persona name to match against
+
+        Returns:
+            True if normalized names match
+        """
+        return self.persona_normalized == normalize_name(persona_name)
+
+    def has_dependency(self, journey_slug: str) -> bool:
+        """Check if this journey depends on another journey.
+
+        Args:
+            journey_slug: Slug of potential dependency
+
+        Returns:
+            True if this journey depends on the given journey
+        """
+        return journey_slug in self.depends_on
+
+    def add_step(self, step: JourneyStep) -> None:
+        """Add a step to this journey.
+
+        Args:
+            step: JourneyStep to add
+        """
+        self.steps.append(step)
+
+    def get_story_refs(self) -> list[str]:
+        """Get all story references from steps.
+
+        Returns:
+            List of story titles referenced in steps
+        """
+        return [step.ref for step in self.steps if step.is_story]
+
+    def get_epic_refs(self) -> list[str]:
+        """Get all epic references from steps.
+
+        Returns:
+            List of epic slugs referenced in steps
+        """
+        return [step.ref for step in self.steps if step.is_epic]
+
+    @property
+    def display_title(self) -> str:
+        """Get formatted title for display."""
+        return self.slug.replace("-", " ").title()
+
+    @property
+    def has_steps(self) -> bool:
+        """Check if journey has any steps."""
+        return len(self.steps) > 0
+
+    @property
+    def step_count(self) -> int:
+        """Get number of steps."""
+        return len(self.steps)

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

@@ -0,0 +1,106 @@
+"""Persona domain model.
+
+Represents a persona derived from story data in the HCD documentation system.
+Personas are not defined directly but are extracted from user stories.
+"""
+
+from pydantic import BaseModel, Field, computed_field, field_validator
+
+from ...utils import normalize_name
+
+
+class Persona(BaseModel):
+    """Persona entity.
+
+    A persona represents a type of user who interacts with the system.
+    Personas are derived from user stories - they are the "As a..." in
+    "As a [persona], I want to...".
+
+    Attributes:
+        name: Display name of the persona (e.g., "Knowledge Curator")
+        app_slugs: List of app slugs this persona uses
+        epic_slugs: List of epic slugs containing stories for this persona
+    """
+
+    name: str
+    app_slugs: list[str] = Field(default_factory=list)
+    epic_slugs: list[str] = Field(default_factory=list)
+
+    @field_validator("name", mode="before")
+    @classmethod
+    def validate_name(cls, v: str) -> str:
+        """Validate name is not empty."""
+        if not v or not v.strip():
+            raise ValueError("name cannot be empty")
+        return v.strip()
+
+    @computed_field
+    @property
+    def normalized_name(self) -> str:
+        """Get normalized name for matching."""
+        return normalize_name(self.name)
+
+    @property
+    def display_name(self) -> str:
+        """Get formatted name for display (same as name)."""
+        return self.name
+
+    @property
+    def app_count(self) -> int:
+        """Get number of apps this persona uses."""
+        return len(self.app_slugs)
+
+    @property
+    def epic_count(self) -> int:
+        """Get number of epics this persona participates in."""
+        return len(self.epic_slugs)
+
+    @property
+    def has_apps(self) -> bool:
+        """Check if persona uses any apps."""
+        return len(self.app_slugs) > 0
+
+    @property
+    def has_epics(self) -> bool:
+        """Check if persona participates in any epics."""
+        return len(self.epic_slugs) > 0
+
+    def uses_app(self, app_slug: str) -> bool:
+        """Check if persona uses a specific app.
+
+        Args:
+            app_slug: App slug to check
+
+        Returns:
+            True if persona uses this app
+        """
+        return app_slug in self.app_slugs
+
+    def participates_in_epic(self, epic_slug: str) -> bool:
+        """Check if persona participates in a specific epic.
+
+        Args:
+            epic_slug: Epic slug to check
+
+        Returns:
+            True if persona has stories in this epic
+        """
+        return epic_slug in self.epic_slugs
+
+    def add_app(self, app_slug: str) -> None:
+        """Add an app to this persona's app list.
+
+        Args:
+            app_slug: App slug to add (duplicates ignored)
+        """
+        if app_slug not in self.app_slugs:
+            self.app_slugs.append(app_slug)
+
+    def add_epic(self, epic_slug: str) -> None:
+        """Add an epic to this persona's epic list.
+
+        Args:
+            epic_slug: Epic slug to add (duplicates ignored)
+        """
+        if epic_slug not in self.epic_slugs:
+            self.epic_slugs.append(epic_slug)

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)