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

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

@@ -0,0 +1,121 @@
+"""Use case for resolving story references.
+
+Finds epics and journeys that reference a specific story.
+"""
+
+from ...utils import normalize_name
+from ..models.epic import Epic
+from ..models.journey import Journey
+from ..models.story import Story
+
+
+def get_epics_for_story(
+    story: Story,
+    epics: list[Epic],
+) -> list[Epic]:
+    """Get epics that contain a specific story.
+
+    Args:
+        story: Story to find epics for
+        epics: All Epic entities to search
+
+    Returns:
+        List of Epic entities containing this story, sorted by slug
+    """
+    story_normalized = normalize_name(story.feature_title)
+    matching = []
+
+    for epic in epics:
+        if any(normalize_name(ref) == story_normalized for ref in epic.story_refs):
+            matching.append(epic)
+
+    return sorted(matching, key=lambda e: e.slug)
+
+
+def get_journeys_for_story(
+    story: Story,
+    journeys: list[Journey],
+) -> list[Journey]:
+    """Get journeys that reference a specific story.
+
+    Args:
+        story: Story to find journeys for
+        journeys: All Journey entities to search
+
+    Returns:
+        List of Journey entities containing this story, sorted by slug
+    """
+    story_normalized = normalize_name(story.feature_title)
+    matching = []
+
+    for journey in journeys:
+        story_refs = journey.get_story_refs()
+        if any(normalize_name(ref) == story_normalized for ref in story_refs):
+            matching.append(journey)
+
+    return sorted(matching, key=lambda j: j.slug)
+
+
+def get_related_stories(
+    story: Story,
+    stories: list[Story],
+    epics: list[Epic],
+) -> list[Story]:
+    """Get stories related to a story via shared epics.
+
+    Finds other stories that are in the same epic(s) as the given story.
+
+    Args:
+        story: Story to find related stories for
+        stories: All Story entities
+        epics: All Epic entities
+
+    Returns:
+        List of related Story entities (excluding the input story), sorted by feature_title
+    """
+    # Find epics containing this story
+    story_epics = get_epics_for_story(story, epics)
+
+    # Collect all story refs from those epics
+    related_refs: set[str] = set()
+    for epic in story_epics:
+        for ref in epic.story_refs:
+            related_refs.add(normalize_name(ref))
+
+    # Remove the original story
+    story_normalized = normalize_name(story.feature_title)
+    related_refs.discard(story_normalized)
+
+    # Find matching stories
+    related = []
+    for s in stories:
+        if normalize_name(s.feature_title) in related_refs:
+            related.append(s)
+
+    return sorted(related, key=lambda s: s.feature_title)
+
+
+def get_story_cross_references(
+    story: Story,
+    stories: list[Story],
+    epics: list[Epic],
+    journeys: list[Journey],
+) -> dict:
+    """Get all cross-references for a story.
+
+    Convenience function to get all related entities at once.
+
+    Args:
+        story: Story to find references for
+        stories: All Story entities
+        epics: All Epic entities
+        journeys: All Journey entities
+
+    Returns:
+        Dict with keys: epics, journeys, related_stories
+    """
+    return {
+        "epics": get_epics_for_story(story, epics),
+        "journeys": get_journeys_for_story(story, journeys),
+        "related_stories": get_related_stories(story, stories, epics),
+    }

julee/docs/sphinx_hcd/parsers/__init__.py

@@ -0,0 +1,48 @@
+"""Parsers for sphinx_hcd.
+
+Contains parsing logic for:
+- gherkin.py: Feature file parsing (.feature files)
+- yaml.py: App and integration manifest parsing
+- ast.py: Python code introspection for accelerators
+"""
+
+from .ast import (
+    parse_bounded_context,
+    parse_module_docstring,
+    parse_python_classes,
+    scan_bounded_contexts,
+)
+from .gherkin import (
+    ParsedFeature,
+    parse_feature_content,
+    parse_feature_file,
+    scan_feature_directory,
+)
+from .yaml import (
+    parse_app_manifest,
+    parse_integration_manifest,
+    parse_manifest_content,
+    scan_app_manifests,
+    scan_integration_manifests,
+)
+
+__all__ = [
+    # AST - Python introspection
+    "parse_bounded_context",
+    "parse_module_docstring",
+    "parse_python_classes",
+    "scan_bounded_contexts",
+    # Gherkin
+    "ParsedFeature",
+    "parse_feature_content",
+    "parse_feature_file",
+    "scan_feature_directory",
+    # YAML - Apps
+    "parse_app_manifest",
+    "scan_app_manifests",
+    # YAML - Integrations
+    "parse_integration_manifest",
+    "scan_integration_manifests",
+    # YAML - Common
+    "parse_manifest_content",
+]

julee/docs/sphinx_hcd/parsers/ast.py

@@ -0,0 +1,150 @@
+"""Python code introspection parser.
+
+Parses Python source files using AST to extract class information
+for ADR 001-compliant bounded contexts.
+"""
+
+import ast
+import logging
+from pathlib import Path
+
+from ..domain.models.code_info import BoundedContextInfo, ClassInfo
+
+logger = logging.getLogger(__name__)
+
+
+def parse_python_classes(directory: Path) -> list[ClassInfo]:
+    """Extract class information from Python files in a directory using AST.
+
+    Args:
+        directory: Directory to scan for .py files
+
+    Returns:
+        List of ClassInfo objects sorted by class name
+    """
+    if not directory.exists():
+        return []
+
+    classes = []
+    for py_file in directory.glob("*.py"):
+        if py_file.name.startswith("_"):
+            continue
+
+        try:
+            source = py_file.read_text()
+            tree = ast.parse(source, filename=str(py_file))
+
+            for node in ast.walk(tree):
+                if isinstance(node, ast.ClassDef):
+                    docstring = ast.get_docstring(node) or ""
+                    first_line = docstring.split("\n")[0].strip() if docstring else ""
+                    classes.append(
+                        ClassInfo(
+                            name=node.name,
+                            docstring=first_line,
+                            file=py_file.name,
+                        )
+                    )
+        except SyntaxError as e:
+            logger.warning(f"Syntax error in {py_file}: {e}")
+        except Exception as e:
+            logger.warning(f"Could not parse {py_file}: {e}")
+
+    return sorted(classes, key=lambda c: c.name)
+
+
+def parse_module_docstring(module_path: Path) -> tuple[str | None, str | None]:
+    """Extract module docstring from a Python file using AST.
+
+    Args:
+        module_path: Path to Python file
+
+    Returns:
+        Tuple of (first_line, full_docstring) or (None, None) if not found
+    """
+    if not module_path.exists():
+        return None, None
+
+    try:
+        source = module_path.read_text()
+        tree = ast.parse(source, filename=str(module_path))
+        docstring = ast.get_docstring(tree)
+        if docstring:
+            first_line = docstring.split("\n")[0].strip()
+            return first_line, docstring
+    except SyntaxError as e:
+        logger.warning(f"Syntax error in {module_path}: {e}")
+    except Exception as e:
+        logger.warning(f"Could not parse {module_path}: {e}")
+
+    return None, None
+
+
+def parse_bounded_context(context_dir: Path) -> BoundedContextInfo | None:
+    """Introspect a bounded context directory for ADR 001-compliant code structure.
+
+    Expected directory structure:
+    - context_dir/
+      - __init__.py (module docstring becomes objective)
+      - domain/
+        - models/ (entities)
+        - repositories/ (repository protocols)
+        - services/ (service protocols)
+      - use_cases/ (use case classes)
+      - infrastructure/ (optional)
+
+    Args:
+        context_dir: Path to the bounded context directory
+
+    Returns:
+        BoundedContextInfo if directory exists, None otherwise
+    """
+    if not context_dir.exists() or not context_dir.is_dir():
+        return None
+
+    init_file = context_dir / "__init__.py"
+    objective, full_docstring = parse_module_docstring(init_file)
+
+    return BoundedContextInfo(
+        slug=context_dir.name,
+        entities=parse_python_classes(context_dir / "domain" / "models"),
+        use_cases=parse_python_classes(context_dir / "use_cases"),
+        repository_protocols=parse_python_classes(
+            context_dir / "domain" / "repositories"
+        ),
+        service_protocols=parse_python_classes(context_dir / "domain" / "services"),
+        has_infrastructure=(context_dir / "infrastructure").exists(),
+        code_dir=context_dir.name,
+        objective=objective,
+        docstring=full_docstring,
+    )
+
+
+def scan_bounded_contexts(src_dir: Path) -> list[BoundedContextInfo]:
+    """Scan a source directory for all bounded contexts.
+
+    Args:
+        src_dir: Root source directory (e.g., project/src/)
+
+    Returns:
+        List of BoundedContextInfo objects for all discovered contexts
+    """
+    if not src_dir.exists():
+        logger.info(f"Source directory not found: {src_dir}")
+        return []
+
+    contexts = []
+    for context_dir in src_dir.iterdir():
+        if not context_dir.is_dir():
+            continue
+        if context_dir.name.startswith((".", "_")):
+            continue
+
+        context_info = parse_bounded_context(context_dir)
+        if context_info:
+            contexts.append(context_info)
+            logger.info(
+                f"Introspected bounded context '{context_info.slug}': {context_info.summary()}"
+            )
+
+    return contexts

julee/docs/sphinx_hcd/parsers/gherkin.py

@@ -0,0 +1,155 @@
+"""Gherkin feature file parser.
+
+Parses .feature files to extract user story information.
+"""
+
+import logging
+import re
+from dataclasses import dataclass
+from pathlib import Path
+
+from ..domain.models.story import Story
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class ParsedFeature:
+    """Raw parsed data from a feature file.
+
+    This intermediate representation holds the extracted values
+    before creating a Story entity.
+    """
+
+    feature_title: str
+    persona: str
+    i_want: str
+    so_that: str
+    gherkin_snippet: str
+
+
+def parse_feature_content(content: str) -> ParsedFeature:
+    """Parse the content of a Gherkin feature file.
+
+    Extracts:
+    - Feature: <title>
+    - As a <persona>
+    - I want to <action>
+    - So that <benefit>
+    - The story header (everything before Scenario/Background)
+
+    Args:
+        content: The full text content of a .feature file
+
+    Returns:
+        ParsedFeature with extracted values (defaults for missing fields)
+    """
+    # Extract header components using regex
+    feature_match = re.search(r"^Feature:\s*(.+)$", content, re.MULTILINE)
+    as_a_match = re.search(r"^\s*As an?\s+(.+)$", content, re.MULTILINE)
+    i_want_match = re.search(r"^\s*I want to\s+(.+)$", content, re.MULTILINE)
+    so_that_match = re.search(r"^\s*So that\s+(.+)$", content, re.MULTILINE)
+
+    # Extract Gherkin snippet (story header only, stop before scenarios)
+    lines = content.split("\n")
+    snippet_lines = []
+    for line in lines:
+        stripped = line.strip()
+        # Stop at scenario markers or step keywords at start of line
+        if stripped.startswith(
+            ("Scenario", "Background", "@", "Given", "When", "Then", "And", "But")
+        ):
+            break
+        if stripped:
+            snippet_lines.append(line)
+    gherkin_snippet = "\n".join(snippet_lines)
+
+    return ParsedFeature(
+        feature_title=feature_match.group(1).strip() if feature_match else "Unknown",
+        persona=as_a_match.group(1).strip() if as_a_match else "unknown",
+        i_want=i_want_match.group(1).strip() if i_want_match else "do something",
+        so_that=so_that_match.group(1).strip() if so_that_match else "achieve a goal",
+        gherkin_snippet=gherkin_snippet,
+    )
+
+
+def parse_feature_file(
+    file_path: Path,
+    project_root: Path,
+    app_slug: str | None = None,
+) -> Story | None:
+    """Parse a single feature file and return a Story.
+
+    Args:
+        file_path: Absolute path to the .feature file
+        project_root: Project root for computing relative paths
+        app_slug: Optional app slug override. If None, extracted from path.
+
+    Returns:
+        Story entity, or None if parsing fails
+    """
+    try:
+        content = file_path.read_text()
+    except Exception as e:
+        logger.warning(f"Could not read {file_path}: {e}")
+        return None
+
+    # Parse the content
+    parsed = parse_feature_content(content)
+
+    # Compute relative path
+    try:
+        rel_path = file_path.relative_to(project_root)
+    except ValueError:
+        rel_path = file_path
+        logger.warning(f"Feature file {file_path} is not under project root")
+
+    # Extract app slug from path if not provided
+    # Expected: tests/e2e/{app}/features/{name}.feature
+    if app_slug is None:
+        parts = rel_path.parts
+        if len(parts) >= 4 and parts[2] != "features":
+            app_slug = parts[2]
+        else:
+            app_slug = "unknown"
+
+    return Story.from_feature_file(
+        feature_title=parsed.feature_title,
+        persona=parsed.persona,
+        i_want=parsed.i_want,
+        so_that=parsed.so_that,
+        app_slug=app_slug,
+        file_path=str(rel_path),
+        abs_path=str(file_path),
+        gherkin_snippet=parsed.gherkin_snippet,
+    )
+
+
+def scan_feature_directory(
+    feature_dir: Path,
+    project_root: Path,
+) -> list[Story]:
+    """Scan a directory tree for .feature files and parse them.
+
+    Args:
+        feature_dir: Root directory to scan (e.g., tests/e2e/)
+        project_root: Project root for computing relative paths
+
+    Returns:
+        List of parsed Story entities
+    """
+    stories = []
+
+    if not feature_dir.exists():
+        logger.info(
+            f"Feature files directory not found at {feature_dir} - no stories to index"
+        )
+        return stories
+
+    for feature_file in feature_dir.rglob("*.feature"):
+        story = parse_feature_file(feature_file, project_root)
+        if story:
+            stories.append(story)
+
+    logger.info(f"Indexed {len(stories)} Gherkin stories from {feature_dir}")
+    return stories

julee/docs/sphinx_hcd/parsers/yaml.py

@@ -0,0 +1,184 @@
+"""YAML manifest parsers.
+
+Parses YAML manifest files for apps and integrations.
+"""
+
+import logging
+from pathlib import Path
+
+import yaml
+
+from ..domain.models.app import App
+from ..domain.models.integration import Integration
+
+logger = logging.getLogger(__name__)
+
+
+def parse_app_manifest(manifest_path: Path, app_slug: str | None = None) -> App | None:
+    """Parse an app.yaml manifest file.
+
+    Args:
+        manifest_path: Path to the app.yaml file
+        app_slug: Optional app slug override. If None, extracted from directory name.
+
+    Returns:
+        App entity, or None if parsing fails
+    """
+    try:
+        content = manifest_path.read_text()
+    except Exception as e:
+        logger.warning(f"Could not read {manifest_path}: {e}")
+        return None
+
+    try:
+        manifest = yaml.safe_load(content)
+    except yaml.YAMLError as e:
+        logger.warning(f"Could not parse YAML in {manifest_path}: {e}")
+        return None
+
+    if manifest is None:
+        logger.warning(f"Empty manifest at {manifest_path}")
+        return None
+
+    # Extract app slug from directory name if not provided
+    if app_slug is None:
+        app_slug = manifest_path.parent.name
+
+    return App.from_manifest(
+        slug=app_slug,
+        manifest=manifest,
+        manifest_path=str(manifest_path),
+    )
+
+
+def scan_app_manifests(apps_dir: Path) -> list[App]:
+    """Scan a directory for app.yaml manifest files.
+
+    Expects structure: apps_dir/{app-slug}/app.yaml
+
+    Args:
+        apps_dir: Directory containing app subdirectories
+
+    Returns:
+        List of parsed App entities
+    """
+    apps = []
+
+    if not apps_dir.exists():
+        logger.info(
+            f"Apps directory not found at {apps_dir} - no app manifests to index"
+        )
+        return apps
+
+    for app_dir in apps_dir.iterdir():
+        if not app_dir.is_dir():
+            continue
+
+        manifest_path = app_dir / "app.yaml"
+        if not manifest_path.exists():
+            continue
+
+        app = parse_app_manifest(manifest_path)
+        if app:
+            apps.append(app)
+
+    logger.info(f"Indexed {len(apps)} apps from {apps_dir}")
+    return apps
+
+
+def parse_manifest_content(content: str) -> dict | None:
+    """Parse YAML content string.
+
+    A lower-level helper for testing and direct content parsing.
+
+    Args:
+        content: YAML content string
+
+    Returns:
+        Parsed dictionary, or None if parsing fails
+    """
+    try:
+        return yaml.safe_load(content)
+    except yaml.YAMLError as e:
+        logger.warning(f"Could not parse YAML content: {e}")
+        return None
+
+
+# Integration manifest parsing
+
+
+def parse_integration_manifest(
+    manifest_path: Path, module_name: str | None = None
+) -> Integration | None:
+    """Parse an integration.yaml manifest file.
+
+    Args:
+        manifest_path: Path to the integration.yaml file
+        module_name: Optional module name override. If None, extracted from directory name.
+
+    Returns:
+        Integration entity, or None if parsing fails
+    """
+    try:
+        content = manifest_path.read_text()
+    except Exception as e:
+        logger.warning(f"Could not read {manifest_path}: {e}")
+        return None
+
+    try:
+        manifest = yaml.safe_load(content)
+    except yaml.YAMLError as e:
+        logger.warning(f"Could not parse YAML in {manifest_path}: {e}")
+        return None
+
+    if manifest is None:
+        logger.warning(f"Empty manifest at {manifest_path}")
+        return None
+
+    # Extract module name from directory name if not provided
+    if module_name is None:
+        module_name = manifest_path.parent.name
+
+    return Integration.from_manifest(
+        module_name=module_name,
+        manifest=manifest,
+        manifest_path=str(manifest_path),
+    )
+
+
+def scan_integration_manifests(integrations_dir: Path) -> list[Integration]:
+    """Scan a directory for integration.yaml manifest files.
+
+    Expects structure: integrations_dir/{module_name}/integration.yaml
+    Directories starting with '_' are skipped.
+
+    Args:
+        integrations_dir: Directory containing integration subdirectories
+
+    Returns:
+        List of parsed Integration entities
+    """
+    integrations = []
+
+    if not integrations_dir.exists():
+        logger.info(
+            f"Integrations directory not found at {integrations_dir} - "
+            "no integration manifests to index"
+        )
+        return integrations
+
+    for int_dir in integrations_dir.iterdir():
+        # Skip non-directories and directories starting with '_'
+        if not int_dir.is_dir() or int_dir.name.startswith("_"):
+            continue
+
+        manifest_path = int_dir / "integration.yaml"
+        if not manifest_path.exists():
+            continue
+
+        integration = parse_integration_manifest(manifest_path)
+        if integration:
+            integrations.append(integration)
+
+    logger.info(f"Indexed {len(integrations)} integrations from {integrations_dir}")
+    return integrations

julee/docs/sphinx_hcd/repositories/__init__.py

@@ -0,0 +1,4 @@
+"""Repository implementations for sphinx_hcd.
+
+Contains memory repository implementations following julee patterns.
+"""

julee/docs/sphinx_hcd/repositories/memory/__init__.py

@@ -0,0 +1,25 @@
+"""Memory repository implementations for sphinx_hcd.
+
+In-memory implementations used during Sphinx builds. These repositories
+are populated at builder-inited and queried during doctree processing.
+"""
+
+from .accelerator import MemoryAcceleratorRepository
+from .app import MemoryAppRepository
+from .base import MemoryRepositoryMixin
+from .code_info import MemoryCodeInfoRepository
+from .epic import MemoryEpicRepository
+from .integration import MemoryIntegrationRepository
+from .journey import MemoryJourneyRepository
+from .story import MemoryStoryRepository
+
+__all__ = [
+    "MemoryAcceleratorRepository",
+    "MemoryAppRepository",
+    "MemoryCodeInfoRepository",
+    "MemoryEpicRepository",
+    "MemoryIntegrationRepository",
+    "MemoryJourneyRepository",
+    "MemoryRepositoryMixin",
+    "MemoryStoryRepository",
+]