anvil-dev-framework 0.1.6

package/global/tests/test_doc_coverage.py

@@ -0,0 +1,520 @@
+#!/usr/bin/env python3
+"""
+test_doc_coverage.py - Unit tests for doc_coverage_service (ANV-31)
+
+Tests for:
+- DocMapping pattern matching
+- DocIndexer export extraction
+- DocCoverageService coverage calculation
+- Configuration loading
+"""
+
+import os
+import sys
+import tempfile
+import unittest
+from pathlib import Path
+
+# Add parent directory to path for imports
+sys.path.insert(0, str(Path(__file__).parent.parent / "lib"))
+
+from doc_coverage_service import (
+    DocMapping,
+    DocCoverageConfig,
+    DocExport,
+    DocGap,
+    CoverageResult,
+    DocIndexer,
+    DocCoverageService,
+)
+
+
+class TestDocMapping(unittest.TestCase):
+    """Tests for DocMapping class."""
+
+    def test_matches_glob_pattern(self):
+        """Test that glob patterns match correctly."""
+        mapping = DocMapping(
+            source="global/lib/*.py",
+            docs="docs/api/{basename}.md",
+            doc_type="api"
+        )
+
+        self.assertTrue(mapping.matches("global/lib/config_service.py"))
+        self.assertTrue(mapping.matches("global/lib/doc_coverage_service.py"))
+        self.assertFalse(mapping.matches("global/hooks/session_start.py"))
+        self.assertFalse(mapping.matches("src/lib/utils.py"))
+
+    def test_get_doc_path_basename(self):
+        """Test doc path generation with basename template."""
+        mapping = DocMapping(
+            source="global/lib/*.py",
+            docs="docs/api/{basename}.md",
+            doc_type="api"
+        )
+
+        result = mapping.get_doc_path("global/lib/config_service.py")
+        self.assertEqual(result, "docs/api/config_service.md")
+
+    def test_get_doc_path_dirname(self):
+        """Test doc path generation with dirname template."""
+        mapping = DocMapping(
+            source="global/skills/*/skill.md",
+            docs="docs/skills/{dirname}.md",
+            doc_type="skill"
+        )
+
+        result = mapping.get_doc_path("global/skills/linear/skill.md")
+        self.assertEqual(result, "docs/skills/linear.md")
+
+    def test_get_doc_path_filename(self):
+        """Test doc path generation with filename template."""
+        mapping = DocMapping(
+            source=".claude/commands/*.md",
+            docs="docs/commands/{filename}",
+            doc_type="command"
+        )
+
+        result = mapping.get_doc_path(".claude/commands/orient.md")
+        self.assertEqual(result, "docs/commands/orient.md")
+
+
+class TestDocCoverageConfig(unittest.TestCase):
+    """Tests for DocCoverageConfig class."""
+
+    def test_default_config_has_mappings(self):
+        """Test that default config includes standard mappings."""
+        config = DocCoverageConfig.default()
+
+        self.assertTrue(config.enabled)
+        self.assertGreater(len(config.mappings), 0)
+        self.assertEqual(config.thresholds["warning"], 80)
+        self.assertEqual(config.thresholds["critical"], 60)
+
+    def test_default_config_excludes_test_files(self):
+        """Test that default config excludes test files."""
+        config = DocCoverageConfig.default()
+
+        self.assertIn("**/test_*.py", config.exclude)
+        self.assertIn("**/__pycache__/**", config.exclude)
+
+    def test_from_file_returns_default_if_missing(self):
+        """Test that from_file returns default if file doesn't exist."""
+        config = DocCoverageConfig.from_file("/nonexistent/path/config.yaml")
+
+        self.assertTrue(config.enabled)
+        self.assertGreater(len(config.mappings), 0)
+
+
+class TestDocIndexer(unittest.TestCase):
+    """Tests for DocIndexer class."""
+
+    def setUp(self):
+        """Set up test fixtures."""
+        self.config = DocCoverageConfig.default()
+        self.indexer = DocIndexer(self.config)
+
+    def test_extract_python_function(self):
+        """Test extracting function exports from Python code."""
+        with tempfile.NamedTemporaryFile(mode="w", suffix=".py", delete=False) as f:
+            f.write('''
+def public_function(arg1: str, arg2: int = 0) -> bool:
+    """This is a public function."""
+    return True
+
+def _private_function():
+    """This should be skipped."""
+    pass
+''')
+            f.flush()
+
+            try:
+                exports = self.indexer._extract_python_exports(f.name, "test.py")
+
+                # Should find public function but not private
+                names = [e.name for e in exports]
+                self.assertIn("public_function", names)
+                self.assertNotIn("_private_function", names)
+
+                # Check function details
+                public_fn = next(e for e in exports if e.name == "public_function")
+                self.assertEqual(public_fn.export_type, "function")
+                self.assertIsNotNone(public_fn.docstring)
+                self.assertIn("arg1", public_fn.signature)
+            finally:
+                os.unlink(f.name)
+
+    def test_extract_python_class(self):
+        """Test extracting class exports from Python code."""
+        with tempfile.NamedTemporaryFile(mode="w", suffix=".py", delete=False) as f:
+            f.write('''
+class PublicClass:
+    """A public class for testing."""
+
+    def method(self):
+        pass
+
+class _PrivateClass:
+    """Should be skipped."""
+    pass
+''')
+            f.flush()
+
+            try:
+                exports = self.indexer._extract_python_exports(f.name, "test.py")
+
+                names = [e.name for e in exports]
+                self.assertIn("PublicClass", names)
+                self.assertNotIn("_PrivateClass", names)
+
+                public_cls = next(e for e in exports if e.name == "PublicClass")
+                self.assertEqual(public_cls.export_type, "class")
+            finally:
+                os.unlink(f.name)
+
+    def test_extract_python_constant(self):
+        """Test extracting constant exports from Python code."""
+        with tempfile.NamedTemporaryFile(mode="w", suffix=".py", delete=False) as f:
+            f.write('''
+PUBLIC_CONSTANT = "value"
+ANOTHER_CONST = 42
+_private_var = "hidden"
+lowercase_var = "not exported"
+''')
+            f.flush()
+
+            try:
+                exports = self.indexer._extract_python_exports(f.name, "test.py")
+
+                names = [e.name for e in exports]
+                self.assertIn("PUBLIC_CONSTANT", names)
+                self.assertIn("ANOTHER_CONST", names)
+                self.assertNotIn("_private_var", names)
+                self.assertNotIn("lowercase_var", names)
+            finally:
+                os.unlink(f.name)
+
+    def test_is_excluded(self):
+        """Test file exclusion patterns."""
+        self.assertTrue(self.indexer._is_excluded("tests/test_something.py"))
+        self.assertTrue(self.indexer._is_excluded("dir/__pycache__/module.py"))
+        self.assertTrue(self.indexer._is_excluded("node_modules/package/index.js"))
+        self.assertFalse(self.indexer._is_excluded("global/lib/service.py"))
+
+
+class TestCoverageResult(unittest.TestCase):
+    """Tests for CoverageResult class."""
+
+    def test_status_healthy(self):
+        """Test healthy status for high coverage."""
+        result = CoverageResult(
+            total_exports=100,
+            documented_exports=85,
+            coverage_percent=85.0,
+            gaps=[],
+            by_type={}
+        )
+
+        self.assertEqual(result.status, "healthy")
+        self.assertEqual(result.status_emoji, "✅")
+
+    def test_status_warning(self):
+        """Test warning status for medium coverage."""
+        result = CoverageResult(
+            total_exports=100,
+            documented_exports=70,
+            coverage_percent=70.0,
+            gaps=[],
+            by_type={}
+        )
+
+        self.assertEqual(result.status, "warning")
+        self.assertEqual(result.status_emoji, "⚠️")
+
+    def test_status_critical(self):
+        """Test critical status for low coverage."""
+        result = CoverageResult(
+            total_exports=100,
+            documented_exports=50,
+            coverage_percent=50.0,
+            gaps=[],
+            by_type={}
+        )
+
+        self.assertEqual(result.status, "critical")
+        self.assertEqual(result.status_emoji, "❌")
+
+
+class TestDocCoverageService(unittest.TestCase):
+    """Tests for DocCoverageService class."""
+
+    def test_calculate_coverage_returns_result(self):
+        """Test that calculate_coverage returns a CoverageResult."""
+        # Use current project directory
+        service = DocCoverageService(project_path=".")
+        result = service.calculate_coverage()
+
+        self.assertIsInstance(result, CoverageResult)
+        self.assertGreaterEqual(result.total_exports, 0)
+        self.assertGreaterEqual(result.coverage_percent, 0)
+        self.assertLessEqual(result.coverage_percent, 100)
+
+    def test_check_threshold(self):
+        """Test check method with thresholds."""
+        service = DocCoverageService(project_path=".")
+
+        # This should work regardless of actual coverage
+        result_low = service.check(threshold=0)
+        self.assertTrue(result_low)
+
+        # High threshold check - result depends on actual coverage
+        _ = service.check(threshold=100)
+
+    def test_generate_report_markdown(self):
+        """Test markdown report generation."""
+        service = DocCoverageService(project_path=".")
+        report = service.generate_report(output_format="markdown")
+
+        self.assertIn("# Documentation Coverage Report", report)
+        self.assertIn("## Summary", report)
+        self.assertIn("Coverage", report)
+
+    def test_generate_report_json(self):
+        """Test JSON report generation."""
+        import json
+
+        service = DocCoverageService(project_path=".")
+        report = service.generate_report(output_format="json")
+
+        # Should be valid JSON
+        data = json.loads(report)
+        self.assertIn("total_exports", data)
+        self.assertIn("coverage_percent", data)
+        self.assertIn("status", data)
+
+
+class TestDocExport(unittest.TestCase):
+    """Tests for DocExport class."""
+
+    def test_qualified_name(self):
+        """Test qualified name generation."""
+        export = DocExport(
+            name="my_function",
+            export_type="function",
+            source_file="path/to/module.py",
+            line_number=42
+        )
+
+        self.assertEqual(export.qualified_name, "path/to/module.py:my_function")
+
+
+# =============================================================================
+# Gap Detection Tests (ANV-218)
+# =============================================================================
+
+# Import gap detection classes
+from doc_coverage_service import (
+    StaleDocWarning,
+    GapDetectionResult,
+    GapDetector,
+)
+
+
+class TestStaleDocWarning(unittest.TestCase):
+    """Tests for StaleDocWarning dataclass."""
+
+    def test_message_property(self):
+        """Test human-readable warning message generation."""
+        warning = StaleDocWarning(
+            source_file="global/lib/service.py",
+            doc_file="docs/api/service.md",
+            source_mtime=1700000000.0,
+            doc_mtime=1699000000.0,
+            days_stale=12,
+            severity="warning"
+        )
+
+        message = warning.message
+        self.assertIn("service.md", message)
+        self.assertIn("12 days", message)
+        self.assertIn("stale", message.lower())
+
+    def test_severity_levels(self):
+        """Test different severity levels."""
+        for severity in ["info", "warning", "critical"]:
+            warning = StaleDocWarning(
+                source_file="test.py",
+                doc_file="test.md",
+                source_mtime=1700000000.0,
+                doc_mtime=1699000000.0,
+                days_stale=5,
+                severity=severity
+            )
+            self.assertEqual(warning.severity, severity)
+
+
+class TestGapDetectionResult(unittest.TestCase):
+    """Tests for GapDetectionResult dataclass."""
+
+    def test_to_context_block_with_warnings(self):
+        """Test context block generation with warnings."""
+        warnings = [
+            StaleDocWarning(
+                source_file="global/lib/service.py",
+                doc_file="docs/api/service.md",
+                source_mtime=1700000000.0,
+                doc_mtime=1699000000.0,
+                days_stale=7,
+                severity="warning"
+            )
+        ]
+        result = GapDetectionResult(
+            stale_docs=warnings,
+            changed_files_without_docs=["global/lib/new_module.py"],
+            total_warnings=2,
+            sensitivity="balanced"
+        )
+
+        context = result.to_context_block()
+
+        # Should include header
+        self.assertIn("Documentation Coverage Warnings", context)
+        # Should include stale doc warning
+        self.assertIn("service.md", context)
+        # Should include changed file without docs
+        self.assertIn("new_module.py", context)
+
+    def test_to_context_block_empty(self):
+        """Test context block is empty when no warnings."""
+        result = GapDetectionResult(
+            stale_docs=[],
+            changed_files_without_docs=[],
+            total_warnings=0,
+            sensitivity="balanced"
+        )
+
+        context = result.to_context_block()
+        self.assertEqual(context, "")
+
+    def test_total_warnings_count(self):
+        """Test total warnings includes both stale and changed."""
+        warnings = [
+            StaleDocWarning(
+                source_file="a.py",
+                doc_file="a.md",
+                source_mtime=1700000000.0,
+                doc_mtime=1699000000.0,
+                days_stale=5,
+                severity="info"
+            )
+        ]
+        result = GapDetectionResult(
+            stale_docs=warnings,
+            changed_files_without_docs=["b.py", "c.py"],
+            total_warnings=3,
+            sensitivity="balanced"
+        )
+
+        self.assertEqual(result.total_warnings, 3)
+
+
+class TestGapDetector(unittest.TestCase):
+    """Tests for GapDetector class."""
+
+    def setUp(self):
+        """Set up test fixtures."""
+        self.config = DocCoverageConfig.default()
+
+    def test_sensitivity_thresholds(self):
+        """Test sensitivity threshold configuration."""
+        # Aggressive - 0 days threshold
+        detector = GapDetector(self.config, sensitivity="aggressive")
+        self.assertEqual(detector.sensitivity, "aggressive")
+        self.assertEqual(GapDetector.SENSITIVITY_THRESHOLDS["aggressive"], 0)
+
+        # Balanced - 7 days threshold
+        detector = GapDetector(self.config, sensitivity="balanced")
+        self.assertEqual(GapDetector.SENSITIVITY_THRESHOLDS["balanced"], 7)
+
+        # Quiet - 30 days threshold
+        detector = GapDetector(self.config, sensitivity="quiet")
+        self.assertEqual(GapDetector.SENSITIVITY_THRESHOLDS["quiet"], 30)
+
+    def test_analyze_returns_result(self):
+        """Test that analyze returns a GapDetectionResult."""
+        detector = GapDetector(self.config, sensitivity="quiet")
+        result = detector.analyze(".")
+
+        self.assertIsInstance(result, GapDetectionResult)
+        self.assertEqual(result.sensitivity, "quiet")
+        self.assertIsInstance(result.stale_docs, list)
+        self.assertIsInstance(result.changed_files_without_docs, list)
+
+
+class TestGapDetectionService(unittest.TestCase):
+    """Tests for gap detection service methods."""
+
+    def test_detect_stale_docs_returns_result(self):
+        """Test detect_stale_docs returns a GapDetectionResult."""
+        service = DocCoverageService(project_path=".")
+        result = service.detect_stale_docs()
+
+        self.assertIsInstance(result, GapDetectionResult)
+
+    def test_detect_stale_docs_respects_sensitivity(self):
+        """Test detect_stale_docs uses provided sensitivity."""
+        service = DocCoverageService(project_path=".")
+
+        result_quiet = service.detect_stale_docs(sensitivity="quiet")
+        self.assertEqual(result_quiet.sensitivity, "quiet")
+
+        result_aggressive = service.detect_stale_docs(sensitivity="aggressive")
+        self.assertEqual(result_aggressive.sensitivity, "aggressive")
+
+    def test_detect_stale_docs_disabled_via_config(self):
+        """Test that gap detection returns empty when disabled."""
+        config = DocCoverageConfig.default()
+        config.gap_detection_enabled = False
+
+        service = DocCoverageService(project_path=".", config=config)
+        result = service.detect_stale_docs()
+
+        # Should return empty result when disabled
+        self.assertEqual(result.total_warnings, 0)
+        self.assertEqual(len(result.stale_docs), 0)
+        self.assertEqual(len(result.changed_files_without_docs), 0)
+
+    def test_get_session_warnings_returns_string(self):
+        """Test get_session_warnings returns a string."""
+        service = DocCoverageService(project_path=".")
+        warnings = service.get_session_warnings()
+
+        self.assertIsInstance(warnings, str)
+
+    def test_get_session_warnings_empty_when_disabled(self):
+        """Test get_session_warnings returns empty when disabled."""
+        config = DocCoverageConfig.default()
+        config.gap_detection_enabled = False
+
+        service = DocCoverageService(project_path=".", config=config)
+        warnings = service.get_session_warnings()
+
+        self.assertEqual(warnings, "")
+
+
+class TestGapDetectionConfig(unittest.TestCase):
+    """Tests for gap detection configuration."""
+
+    def test_default_config_has_gap_detection_enabled(self):
+        """Test default config has gap detection enabled."""
+        config = DocCoverageConfig.default()
+        self.assertTrue(config.gap_detection_enabled)
+
+    def test_default_config_has_sensitivity(self):
+        """Test default config has sensitivity setting."""
+        config = DocCoverageConfig.default()
+        self.assertEqual(config.sensitivity, "balanced")
+
+
+if __name__ == "__main__":
+    unittest.main()