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

julee/docs/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/docs/sphinx_hcd/domain/models/accelerator.py

@@ -0,0 +1,152 @@
+"""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 BaseModel, Field, field_validator
+
+
+class IntegrationReference(BaseModel):
+    """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.
+
+    Attributes:
+        slug: Integration slug (e.g., "pilot-data-collection")
+        description: What is sourced/published (e.g., "Scheme documentation")
+    """
+
+    slug: str
+    description: 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()
+
+    @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(BaseModel):
+    """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.
+
+    Attributes:
+        slug: URL-safe identifier (e.g., "vocabulary")
+        status: Development status (e.g., "alpha", "production", "future")
+        milestone: Target milestone (e.g., "2 (Nov 2025)")
+        acceptance: Acceptance criteria description
+        objective: Business objective/description
+        sources_from: Integrations this accelerator reads from
+        feeds_into: Other accelerators this one feeds data into
+        publishes_to: Integrations this accelerator writes to
+        depends_on: Other accelerators this one depends on
+        docname: RST document name (for incremental builds)
+    """
+
+    slug: str
+    status: str = ""
+    milestone: str | None = None
+    acceptance: str | None = None
+    objective: str = ""
+    sources_from: list[IntegrationReference] = Field(default_factory=list)
+    feeds_into: list[str] = Field(default_factory=list)
+    publishes_to: list[IntegrationReference] = Field(default_factory=list)
+    depends_on: 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()
+
+    @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

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

@@ -0,0 +1,151 @@
+"""App domain model.
+
+Represents an application in the HCD documentation system.
+Apps are defined via YAML manifests in apps/*/app.yaml.
+"""
+
+from enum import Enum
+
+from pydantic import BaseModel, Field, field_validator
+
+from ...utils import normalize_name
+
+
+class AppType(str, Enum):
+    """Application type classification."""
+
+    STAFF = "staff"
+    EXTERNAL = "external"
+    MEMBER_TOOL = "member-tool"
+    UNKNOWN = "unknown"
+
+    @classmethod
+    def from_string(cls, value: str) -> "AppType":
+        """Convert string to AppType, defaulting to UNKNOWN."""
+        try:
+            return cls(value.lower())
+        except ValueError:
+            return cls.UNKNOWN
+
+
+class App(BaseModel):
+    """Application entity.
+
+    Apps represent distinct applications in the system, defined via YAML
+    manifests. They serve as containers for stories and provide organization
+    for the documentation.
+
+    Attributes:
+        slug: URL-safe identifier (e.g., "staff-portal")
+        name: Display name (e.g., "Staff Portal")
+        app_type: Classification (staff, external, member-tool)
+        status: Optional status indicator (e.g., "in-development", "live")
+        description: Human-readable description
+        accelerators: List of accelerator slugs associated with this app
+        manifest_path: Path to the app.yaml file
+        name_normalized: Lowercase name for matching
+    """
+
+    slug: str
+    name: str
+    app_type: AppType = AppType.UNKNOWN
+    status: str | None = None
+    description: str = ""
+    accelerators: list[str] = 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("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,
+        slug: str,
+        manifest: dict,
+        manifest_path: str,
+    ) -> "App":
+        """Create an App from a parsed YAML manifest.
+
+        Args:
+            slug: App slug (usually directory name)
+            manifest: Parsed YAML content
+            manifest_path: Path to the manifest file
+
+        Returns:
+            App instance
+        """
+        name = manifest.get("name", slug.replace("-", " ").title())
+        app_type = AppType.from_string(manifest.get("type", "unknown"))
+
+        return cls(
+            slug=slug,
+            name=name,
+            app_type=app_type,
+            status=manifest.get("status"),
+            description=manifest.get("description", "").strip(),
+            accelerators=manifest.get("accelerators", []),
+            manifest_path=manifest_path,
+        )
+
+    def matches_type(self, app_type: AppType | str) -> bool:
+        """Check if this app matches the given type.
+
+        Args:
+            app_type: AppType enum or string to match
+
+        Returns:
+            True if app matches the type
+        """
+        if isinstance(app_type, str):
+            app_type = AppType.from_string(app_type)
+        return self.app_type == app_type
+
+    def matches_name(self, name: str) -> bool:
+        """Check if this app 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)
+
+    @property
+    def type_label(self) -> str:
+        """Get human-readable type label."""
+        labels = {
+            AppType.STAFF: "Staff Application",
+            AppType.EXTERNAL: "External Application",
+            AppType.MEMBER_TOOL: "Member Tool",
+            AppType.UNKNOWN: "Unknown",
+        }
+        return labels.get(self.app_type, str(self.app_type))

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

@@ -0,0 +1,121 @@
+"""Code introspection domain models.
+
+Models for representing Python code structure extracted via AST parsing.
+Used to document bounded contexts and their ADR 001-compliant structure.
+"""
+
+from pydantic import BaseModel, Field, field_validator
+
+
+class ClassInfo(BaseModel):
+    """Information about a Python class extracted via AST.
+
+    Attributes:
+        name: Class name (e.g., "Document", "CreateDocumentUseCase")
+        docstring: First line of the class docstring
+        file: Source file name (e.g., "document.py")
+    """
+
+    name: str
+    docstring: str = ""
+    file: 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()
+
+
+class BoundedContextInfo(BaseModel):
+    """Information about a bounded context's code structure.
+
+    Represents the ADR 001-compliant structure of a bounded context
+    with domain models, use cases, and repository/service protocols.
+
+    Attributes:
+        slug: Directory name / identifier (e.g., "vocabulary")
+        entities: Domain entity classes from domain/models/
+        use_cases: Use case classes from use_cases/
+        repository_protocols: Repository protocol classes from domain/repositories/
+        service_protocols: Service protocol classes from domain/services/
+        has_infrastructure: Whether infrastructure/ directory exists
+        code_dir: Actual directory name in src/
+        objective: First line of __init__.py docstring
+        docstring: Full __init__.py docstring
+    """
+
+    slug: str
+    entities: list[ClassInfo] = Field(default_factory=list)
+    use_cases: list[ClassInfo] = Field(default_factory=list)
+    repository_protocols: list[ClassInfo] = Field(default_factory=list)
+    service_protocols: list[ClassInfo] = Field(default_factory=list)
+    has_infrastructure: bool = False
+    code_dir: str = ""
+    objective: str | None = None
+    docstring: str | None = None
+
+    @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 entity_count(self) -> int:
+        """Get number of domain entities."""
+        return len(self.entities)
+
+    @property
+    def use_case_count(self) -> int:
+        """Get number of use cases."""
+        return len(self.use_cases)
+
+    @property
+    def protocol_count(self) -> int:
+        """Get total number of protocols (repository + service)."""
+        return len(self.repository_protocols) + len(self.service_protocols)
+
+    @property
+    def has_entities(self) -> bool:
+        """Check if bounded context has any entities."""
+        return len(self.entities) > 0
+
+    @property
+    def has_use_cases(self) -> bool:
+        """Check if bounded context has any use cases."""
+        return len(self.use_cases) > 0
+
+    @property
+    def has_protocols(self) -> bool:
+        """Check if bounded context has any protocols."""
+        return self.protocol_count > 0
+
+    def get_entity_names(self) -> list[str]:
+        """Get list of entity class names."""
+        return [e.name for e in self.entities]
+
+    def get_use_case_names(self) -> list[str]:
+        """Get list of use case class names."""
+        return [u.name for u in self.use_cases]
+
+    def summary(self) -> str:
+        """Get a brief summary of the bounded context.
+
+        Returns:
+            Summary string like "3 entities, 2 use cases"
+        """
+        parts = []
+        if self.entities:
+            parts.append(f"{len(self.entities)} entities")
+        if self.use_cases:
+            parts.append(f"{len(self.use_cases)} use cases")
+        if self.repository_protocols:
+            parts.append(f"{len(self.repository_protocols)} repository protocols")
+        if self.service_protocols:
+            parts.append(f"{len(self.service_protocols)} service protocols")
+        return ", ".join(parts) if parts else "empty"

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

@@ -0,0 +1,79 @@
+"""Epic domain model.
+
+Represents an epic in the HCD documentation system.
+Epics are defined via RST directives and group related stories together.
+"""
+
+from pydantic import BaseModel, Field, field_validator
+
+from ...utils import normalize_name
+
+
+class Epic(BaseModel):
+    """Epic entity.
+
+    An epic represents a collection of related stories that together
+    deliver a larger piece of functionality or business value.
+
+    Attributes:
+        slug: URL-safe identifier (e.g., "credential-creation")
+        description: Human-readable description of the epic
+        story_refs: List of story feature titles in this epic
+        docname: RST document name (for incremental builds)
+    """
+
+    slug: str
+    description: str = ""
+    story_refs: 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()
+
+    def add_story(self, story_title: str) -> None:
+        """Add a story reference to this epic.
+
+        Args:
+            story_title: Feature title of the story to add
+        """
+        self.story_refs.append(story_title)
+
+    def has_story(self, story_title: str) -> bool:
+        """Check if this epic contains a specific story.
+
+        Args:
+            story_title: Feature title to check (case-insensitive)
+
+        Returns:
+            True if the story is in this epic
+        """
+        story_normalized = normalize_name(story_title)
+        return any(normalize_name(ref) == story_normalized for ref in self.story_refs)
+
+    def get_story_refs_normalized(self) -> list[str]:
+        """Get normalized story references.
+
+        Returns:
+            List of normalized story titles
+        """
+        return [normalize_name(ref) for ref in self.story_refs]
+
+    @property
+    def display_title(self) -> str:
+        """Get formatted title for display."""
+        return self.slug.replace("-", " ").title()
+
+    @property
+    def story_count(self) -> int:
+        """Get number of stories in this epic."""
+        return len(self.story_refs)
+
+    @property
+    def has_stories(self) -> bool:
+        """Check if epic has any stories."""
+        return len(self.story_refs) > 0