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

julee/docs/sphinx_hcd/tests/parsers/test_ast.py

@@ -0,0 +1,298 @@
+"""Tests for AST parser."""
+
+from pathlib import Path
+
+from julee.docs.sphinx_hcd.parsers.ast import (
+    parse_bounded_context,
+    parse_module_docstring,
+    parse_python_classes,
+    scan_bounded_contexts,
+)
+
+
+class TestParsePythonClasses:
+    """Test parse_python_classes function."""
+
+    def test_parse_single_class(self, tmp_path: Path) -> None:
+        """Test parsing a file with a single class."""
+        py_file = tmp_path / "document.py"
+        py_file.write_text(
+            '''
+class Document:
+    """A document entity."""
+    pass
+'''
+        )
+
+        classes = parse_python_classes(tmp_path)
+        assert len(classes) == 1
+        assert classes[0].name == "Document"
+        assert classes[0].docstring == "A document entity."
+        assert classes[0].file == "document.py"
+
+    def test_parse_multiple_classes(self, tmp_path: Path) -> None:
+        """Test parsing a file with multiple classes."""
+        py_file = tmp_path / "models.py"
+        py_file.write_text(
+            '''
+class Document:
+    """A document entity."""
+    pass
+
+class Term:
+    """A term in a vocabulary."""
+    pass
+'''
+        )
+
+        classes = parse_python_classes(tmp_path)
+        assert len(classes) == 2
+        names = {c.name for c in classes}
+        assert names == {"Document", "Term"}
+
+    def test_parse_class_no_docstring(self, tmp_path: Path) -> None:
+        """Test parsing a class without a docstring."""
+        py_file = tmp_path / "simple.py"
+        py_file.write_text(
+            """
+class SimpleClass:
+    pass
+"""
+        )
+
+        classes = parse_python_classes(tmp_path)
+        assert len(classes) == 1
+        assert classes[0].name == "SimpleClass"
+        assert classes[0].docstring == ""
+
+    def test_parse_multiline_docstring_extracts_first_line(
+        self, tmp_path: Path
+    ) -> None:
+        """Test that only the first line of docstring is extracted."""
+        py_file = tmp_path / "complex.py"
+        py_file.write_text(
+            '''
+class ComplexClass:
+    """First line of docstring.
+
+    More detailed description here.
+    With multiple lines.
+    """
+    pass
+'''
+        )
+
+        classes = parse_python_classes(tmp_path)
+        assert len(classes) == 1
+        assert classes[0].docstring == "First line of docstring."
+
+    def test_skip_private_files(self, tmp_path: Path) -> None:
+        """Test that files starting with underscore are skipped."""
+        (tmp_path / "_private.py").write_text("class Private: pass")
+        (tmp_path / "__init__.py").write_text("class Init: pass")
+        (tmp_path / "public.py").write_text("class Public: pass")
+
+        classes = parse_python_classes(tmp_path)
+        assert len(classes) == 1
+        assert classes[0].name == "Public"
+
+    def test_nonexistent_directory(self) -> None:
+        """Test parsing nonexistent directory returns empty list."""
+        classes = parse_python_classes(Path("/nonexistent/path"))
+        assert classes == []
+
+    def test_sorted_by_name(self, tmp_path: Path) -> None:
+        """Test classes are sorted by name."""
+        py_file = tmp_path / "classes.py"
+        py_file.write_text(
+            """
+class Zebra: pass
+class Apple: pass
+class Mango: pass
+"""
+        )
+
+        classes = parse_python_classes(tmp_path)
+        names = [c.name for c in classes]
+        assert names == ["Apple", "Mango", "Zebra"]
+
+    def test_syntax_error_handled(self, tmp_path: Path) -> None:
+        """Test that syntax errors are handled gracefully."""
+        py_file = tmp_path / "broken.py"
+        py_file.write_text("class Broken def invalid")  # Invalid syntax
+        (tmp_path / "valid.py").write_text("class Valid: pass")
+
+        classes = parse_python_classes(tmp_path)
+        assert len(classes) == 1
+        assert classes[0].name == "Valid"
+
+
+class TestParseModuleDocstring:
+    """Test parse_module_docstring function."""
+
+    def test_parse_module_with_docstring(self, tmp_path: Path) -> None:
+        """Test parsing a module with a docstring."""
+        py_file = tmp_path / "module.py"
+        py_file.write_text(
+            '''"""Module docstring.
+
+More details about the module.
+"""
+
+class SomeClass:
+    pass
+'''
+        )
+
+        first_line, full = parse_module_docstring(py_file)
+        assert first_line == "Module docstring."
+        assert "More details" in full
+
+    def test_parse_module_no_docstring(self, tmp_path: Path) -> None:
+        """Test parsing a module without a docstring."""
+        py_file = tmp_path / "no_doc.py"
+        py_file.write_text(
+            """
+class SomeClass:
+    pass
+"""
+        )
+
+        first_line, full = parse_module_docstring(py_file)
+        assert first_line is None
+        assert full is None
+
+    def test_parse_nonexistent_file(self) -> None:
+        """Test parsing nonexistent file."""
+        first_line, full = parse_module_docstring(Path("/nonexistent/file.py"))
+        assert first_line is None
+        assert full is None
+
+
+class TestParseBoundedContext:
+    """Test parse_bounded_context function."""
+
+    def test_parse_full_context(self, tmp_path: Path) -> None:
+        """Test parsing a complete bounded context structure."""
+        # Create ADR 001-compliant structure
+        context_dir = tmp_path / "vocabulary"
+        (context_dir / "domain" / "models").mkdir(parents=True)
+        (context_dir / "domain" / "repositories").mkdir(parents=True)
+        (context_dir / "domain" / "services").mkdir(parents=True)
+        (context_dir / "use_cases").mkdir(parents=True)
+        (context_dir / "infrastructure").mkdir(parents=True)
+
+        # Module docstring
+        (context_dir / "__init__.py").write_text('"""Vocabulary management."""')
+
+        # Entity
+        (context_dir / "domain" / "models" / "vocabulary.py").write_text(
+            '''
+class Vocabulary:
+    """A vocabulary catalog."""
+    pass
+'''
+        )
+
+        # Use case
+        (context_dir / "use_cases" / "create.py").write_text(
+            '''
+class CreateVocabulary:
+    """Create a new vocabulary."""
+    pass
+'''
+        )
+
+        # Repository protocol
+        (context_dir / "domain" / "repositories" / "vocabulary.py").write_text(
+            '''
+class VocabularyRepository:
+    """Repository for vocabularies."""
+    pass
+'''
+        )
+
+        info = parse_bounded_context(context_dir)
+        assert info is not None
+        assert info.slug == "vocabulary"
+        assert info.objective == "Vocabulary management."
+        assert len(info.entities) == 1
+        assert info.entities[0].name == "Vocabulary"
+        assert len(info.use_cases) == 1
+        assert info.use_cases[0].name == "CreateVocabulary"
+        assert len(info.repository_protocols) == 1
+        assert info.has_infrastructure is True
+        assert info.code_dir == "vocabulary"
+
+    def test_parse_minimal_context(self, tmp_path: Path) -> None:
+        """Test parsing a minimal bounded context."""
+        context_dir = tmp_path / "simple"
+        context_dir.mkdir()
+        (context_dir / "__init__.py").write_text("")
+
+        info = parse_bounded_context(context_dir)
+        assert info is not None
+        assert info.slug == "simple"
+        assert info.entities == []
+        assert info.use_cases == []
+        assert info.has_infrastructure is False
+
+    def test_parse_nonexistent_context(self) -> None:
+        """Test parsing nonexistent context returns None."""
+        info = parse_bounded_context(Path("/nonexistent/context"))
+        assert info is None
+
+
+class TestScanBoundedContexts:
+    """Test scan_bounded_contexts function."""
+
+    def test_scan_multiple_contexts(self, tmp_path: Path) -> None:
+        """Test scanning a directory with multiple contexts."""
+        # Create two contexts
+        for name in ["vocabulary", "traceability"]:
+            context_dir = tmp_path / name
+            context_dir.mkdir()
+            (context_dir / "__init__.py").write_text(f'"""{name.title()} module."""')
+            (context_dir / "domain" / "models").mkdir(parents=True)
+            (context_dir / "domain" / "models" / "entity.py").write_text(
+                f"class {name.title()}Entity: pass"
+            )
+
+        contexts = scan_bounded_contexts(tmp_path)
+        assert len(contexts) == 2
+        slugs = {c.slug for c in contexts}
+        assert slugs == {"vocabulary", "traceability"}
+
+    def test_scan_skips_hidden_directories(self, tmp_path: Path) -> None:
+        """Test that hidden directories are skipped."""
+        (tmp_path / ".hidden").mkdir()
+        (tmp_path / "__pycache__").mkdir()
+        (tmp_path / "_private").mkdir()
+        visible = tmp_path / "visible"
+        visible.mkdir()
+        (visible / "__init__.py").write_text("")
+
+        contexts = scan_bounded_contexts(tmp_path)
+        assert len(contexts) == 1
+        assert contexts[0].slug == "visible"
+
+    def test_scan_skips_files(self, tmp_path: Path) -> None:
+        """Test that files (not directories) are skipped."""
+        (tmp_path / "file.py").write_text("x = 1")
+        context_dir = tmp_path / "context"
+        context_dir.mkdir()
+        (context_dir / "__init__.py").write_text("")
+
+        contexts = scan_bounded_contexts(tmp_path)
+        assert len(contexts) == 1
+        assert contexts[0].slug == "context"
+
+    def test_scan_nonexistent_directory(self) -> None:
+        """Test scanning nonexistent directory returns empty list."""
+        contexts = scan_bounded_contexts(Path("/nonexistent/src"))
+        assert contexts == []
+
+    def test_scan_empty_directory(self, tmp_path: Path) -> None:
+        """Test scanning empty directory returns empty list."""
+        contexts = scan_bounded_contexts(tmp_path)
+        assert contexts == []

julee/docs/sphinx_hcd/tests/parsers/test_gherkin.py

@@ -0,0 +1,282 @@
+"""Tests for Gherkin feature file parser."""
+
+from pathlib import Path
+
+import pytest
+
+from julee.docs.sphinx_hcd.parsers.gherkin import (
+    parse_feature_content,
+    parse_feature_file,
+    scan_feature_directory,
+)
+
+
+class TestParseFeatureContent:
+    """Test parse_feature_content function."""
+
+    def test_parse_complete_feature(self) -> None:
+        """Test parsing a complete feature file."""
+        content = """Feature: Submit Order
+
+  As a Customer
+  I want to submit my order
+  So that I can purchase products
+
+  Scenario: Successful submission
+    Given I have items in my cart
+    When I submit my order
+    Then the order is confirmed
+"""
+        result = parse_feature_content(content)
+
+        assert result.feature_title == "Submit Order"
+        assert result.persona == "Customer"
+        assert result.i_want == "submit my order"
+        assert result.so_that == "I can purchase products"
+        assert "Feature: Submit Order" in result.gherkin_snippet
+        assert "As a Customer" in result.gherkin_snippet
+        # Scenario should not be in snippet
+        assert "Scenario" not in result.gherkin_snippet
+
+    def test_parse_feature_with_as_an(self) -> None:
+        """Test parsing 'As an' variant."""
+        content = """Feature: Admin Dashboard
+
+  As an Administrator
+  I want to view the dashboard
+  So that I can monitor the system
+"""
+        result = parse_feature_content(content)
+        assert result.persona == "Administrator"
+
+    def test_parse_feature_missing_persona(self) -> None:
+        """Test parsing feature without persona defaults to 'unknown'."""
+        content = """Feature: Some Feature
+
+  I want to do something
+  So that I achieve a goal
+"""
+        result = parse_feature_content(content)
+        assert result.persona == "unknown"
+
+    def test_parse_feature_missing_i_want(self) -> None:
+        """Test parsing feature without I want defaults."""
+        content = """Feature: Some Feature
+
+  As a User
+  So that I achieve a goal
+"""
+        result = parse_feature_content(content)
+        assert result.i_want == "do something"
+
+    def test_parse_feature_missing_so_that(self) -> None:
+        """Test parsing feature without So that defaults."""
+        content = """Feature: Some Feature
+
+  As a User
+  I want to do something
+"""
+        result = parse_feature_content(content)
+        assert result.so_that == "achieve a goal"
+
+    def test_parse_feature_missing_title(self) -> None:
+        """Test parsing content without Feature line."""
+        content = """
+  As a User
+  I want to do something
+"""
+        result = parse_feature_content(content)
+        assert result.feature_title == "Unknown"
+
+    def test_snippet_stops_at_background(self) -> None:
+        """Test that snippet extraction stops at Background."""
+        content = """Feature: Test
+
+  As a User
+  I want to test
+
+  Background:
+    Given some setup
+"""
+        result = parse_feature_content(content)
+        assert "Background" not in result.gherkin_snippet
+
+    def test_snippet_stops_at_tags(self) -> None:
+        """Test that snippet extraction stops at tags."""
+        content = """Feature: Test
+
+  As a User
+  I want to test
+
+  @slow @integration
+  Scenario: Tagged scenario
+"""
+        result = parse_feature_content(content)
+        assert "@slow" not in result.gherkin_snippet
+
+    def test_parse_indented_content(self) -> None:
+        """Test parsing with various indentation."""
+        content = """Feature: Upload Document
+
+    As a Staff Member
+    I want to upload a document
+    So that it can be analyzed
+"""
+        result = parse_feature_content(content)
+        assert result.persona == "Staff Member"
+        assert result.i_want == "upload a document"
+
+
+class TestParseFeatureFile:
+    """Test parse_feature_file function."""
+
+    @pytest.fixture
+    def temp_project(self, tmp_path: Path) -> Path:
+        """Create a temporary project structure."""
+        # Create feature directory structure
+        feature_dir = tmp_path / "tests" / "e2e" / "my-app" / "features"
+        feature_dir.mkdir(parents=True)
+        return tmp_path
+
+    def test_parse_feature_file_success(self, temp_project: Path) -> None:
+        """Test parsing a feature file."""
+        feature_dir = temp_project / "tests" / "e2e" / "my-app" / "features"
+        feature_file = feature_dir / "submit.feature"
+        feature_file.write_text(
+            """Feature: Submit Form
+
+  As a User
+  I want to submit a form
+  So that my data is saved
+
+  Scenario: Valid submission
+    Given I fill the form
+    When I submit
+    Then it succeeds
+"""
+        )
+
+        story = parse_feature_file(feature_file, temp_project)
+
+        assert story is not None
+        assert story.feature_title == "Submit Form"
+        assert story.persona == "User"
+        assert story.app_slug == "my-app"
+        assert "tests/e2e/my-app/features/submit.feature" in story.file_path
+
+    def test_parse_feature_file_with_explicit_app(self, temp_project: Path) -> None:
+        """Test parsing with explicit app slug override."""
+        feature_dir = temp_project / "tests" / "e2e" / "my-app" / "features"
+        feature_file = feature_dir / "test.feature"
+        feature_file.write_text("Feature: Test\n\n  As a User\n")
+
+        story = parse_feature_file(feature_file, temp_project, app_slug="override-app")
+
+        assert story is not None
+        assert story.app_slug == "override-app"
+
+    def test_parse_feature_file_nonexistent(self, temp_project: Path) -> None:
+        """Test parsing a nonexistent file returns None."""
+        nonexistent = temp_project / "nonexistent.feature"
+        story = parse_feature_file(nonexistent, temp_project)
+        assert story is None
+
+    def test_parse_feature_file_outside_project_root(self, tmp_path: Path) -> None:
+        """Test parsing a feature file outside the project root logs warning but works."""
+        # Create feature file in tmp_path
+        feature_file = tmp_path / "test.feature"
+        feature_file.write_text("Feature: Test\n\n  As a User\n  I want to test\n")
+
+        # Use a different directory as project root (feature is outside)
+        project_root = tmp_path / "project"
+        project_root.mkdir()
+
+        story = parse_feature_file(feature_file, project_root)
+
+        assert story is not None
+        assert story.feature_title == "Test"
+        # File path should be the full path when outside project root
+        assert str(feature_file) in story.file_path or "test.feature" in story.file_path
+
+    def test_parse_feature_file_unknown_app_slug_structure(
+        self, tmp_path: Path
+    ) -> None:
+        """Test parsing feature file with non-standard path defaults to 'unknown' app."""
+        # Create a feature file not in tests/e2e/{app}/features/ structure
+        feature_dir = tmp_path / "features"
+        feature_dir.mkdir()
+        feature_file = feature_dir / "test.feature"
+        feature_file.write_text("Feature: Test\n\n  As a User\n  I want to test\n")
+
+        story = parse_feature_file(feature_file, tmp_path)
+
+        assert story is not None
+        assert story.app_slug == "unknown"
+
+    def test_parse_feature_file_short_path_defaults_to_unknown(
+        self, tmp_path: Path
+    ) -> None:
+        """Test parsing feature with path too short for app extraction defaults to 'unknown'."""
+        # Create feature file directly in tmp_path (path has < 4 parts)
+        feature_file = tmp_path / "test.feature"
+        feature_file.write_text("Feature: Test\n\n  As a User\n  I want to test\n")
+
+        story = parse_feature_file(feature_file, tmp_path)
+
+        assert story is not None
+        assert story.app_slug == "unknown"
+
+
+class TestScanFeatureDirectory:
+    """Test scan_feature_directory function."""
+
+    @pytest.fixture
+    def temp_project(self, tmp_path: Path) -> Path:
+        """Create a temporary project with multiple apps."""
+        # Create app1 features
+        app1_dir = tmp_path / "tests" / "e2e" / "app-one" / "features"
+        app1_dir.mkdir(parents=True)
+        (app1_dir / "feature1.feature").write_text(
+            "Feature: Feature One\n\n  As a User\n  I want to do one\n"
+        )
+        (app1_dir / "feature2.feature").write_text(
+            "Feature: Feature Two\n\n  As an Admin\n  I want to do two\n"
+        )
+
+        # Create app2 features
+        app2_dir = tmp_path / "tests" / "e2e" / "app-two" / "features"
+        app2_dir.mkdir(parents=True)
+        (app2_dir / "feature3.feature").write_text(
+            "Feature: Feature Three\n\n  As a Customer\n  I want to do three\n"
+        )
+
+        return tmp_path
+
+    def test_scan_finds_all_features(self, temp_project: Path) -> None:
+        """Test scanning finds all feature files."""
+        feature_dir = temp_project / "tests" / "e2e"
+        stories = scan_feature_directory(feature_dir, temp_project)
+
+        assert len(stories) == 3
+        titles = {s.feature_title for s in stories}
+        assert titles == {"Feature One", "Feature Two", "Feature Three"}
+
+    def test_scan_extracts_apps(self, temp_project: Path) -> None:
+        """Test scanning correctly extracts app slugs."""
+        feature_dir = temp_project / "tests" / "e2e"
+        stories = scan_feature_directory(feature_dir, temp_project)
+
+        apps = {s.app_slug for s in stories}
+        assert apps == {"app-one", "app-two"}
+
+    def test_scan_nonexistent_directory(self, tmp_path: Path) -> None:
+        """Test scanning nonexistent directory returns empty list."""
+        stories = scan_feature_directory(tmp_path / "nonexistent", tmp_path)
+        assert stories == []
+
+    def test_scan_empty_directory(self, tmp_path: Path) -> None:
+        """Test scanning empty directory returns empty list."""
+        empty_dir = tmp_path / "empty"
+        empty_dir.mkdir()
+        stories = scan_feature_directory(empty_dir, tmp_path)
+        assert stories == []