Coverage Analyzer

⚠️ MANDATORY: Read Project Documentation First

BEFORE starting coverage analysis, you MUST read and understand the following project documentation:

Core Project Documentation

1. README.md - Project overview, features, and getting started
2. AI_DOCS/project-context.md - Tech stack, architecture, development workflow
3. AI_DOCS/code-conventions.md - Code style, formatting, best practices
4. AI_DOCS/tdd-workflow.md - TDD process, testing standards, coverage requirements

Session Context (if available)

5. .ai-context/ACTIVE_TASKS.md - Current tasks and priorities
6. .ai-context/CONVENTIONS.md - Project-specific conventions
7. .ai-context/RECENT_DECISIONS.md - Recent architectural decisions
8. .ai-context/LAST_SESSION_SUMMARY.md - Previous session summary

Additional AI Documentation

9. AI_DOCS/ai-tools.md - Session management workflow
10. AI_DOCS/ai-skills.md - Other specialized skills/agents available

Why This Matters

• Coverage Requirements: Understand project-specific coverage thresholds (80%+ minimum)
• Testing Patterns: Follow established testing conventions when suggesting tests
• Code Context: Understand module structure and dependencies
• Recent Changes: Be aware of recent test additions or coverage improvements

After reading these files, proceed with your coverage analysis task below.

Overview

Provide advanced test coverage analysis with actionable insights for improving coverage to meet the 80%+ requirement.

When to Use

• After running make coverage to understand gaps
• Before completing a feature (ensure adequate coverage)
• When coverage is below 80% target
• To identify critical uncovered code paths
• For tracking coverage trends over time

What This Skill Provides

✅ Detailed Coverage Analysis

• Current coverage percentage
• Uncovered lines by file
• Missing branches

✅ Actionable Recommendations

• Specific tests to write
• Code locations needing tests
• Priority of coverage gaps

✅ Coverage Gaps Identification

• Critical uncovered paths (error handling)
• Edge cases not tested
• Integration points missing tests

✅ Test Suggestions

• Concrete test code recommendations
• Parametrized test suggestions
• Fixture recommendations

✅ Trend Tracking

• Coverage history over time
• Improvement/regression detection
• Progress toward 80%+ goal

Usage Examples

Analyze Current Coverage

# Generate detailed coverage analysis
analyze test coverage

Output: Comprehensive report with gaps and recommendations

Find Critical Gaps

# Focus on critical uncovered code
show critical coverage gaps

Output: High-priority uncovered code (error handling, security, edge cases)

Get Test Suggestions

# Get specific test recommendations
suggest tests for uncovered code in src/python_modern_template/validators.py

Output: Concrete test cases to add

Track Coverage Trends

# See coverage over time
show coverage trend for last month

Output: Graph showing coverage changes

Step-by-Step Analysis Process

Step 1: Run Coverage

# Generate coverage report
make coverage

This creates:

• Terminal output with overall percentage
• HTML report in htmlcov/
• .coverage data file

Step 2: Parse Coverage Data

Read coverage data from multiple sources:

# Read terminal output for overall stats
# Read htmlcov/index.html for detailed breakdown
# Parse .coverage file for line-by-line data

Step 3: Identify Uncovered Lines

For each source file:

• List uncovered line numbers
• Group by type (functions, error handling, edge cases)
• Prioritize by criticality

Step 4: Analyze Context

For each uncovered section:

• Read surrounding code
• Understand what the code does
• Identify why it's not covered
• Determine appropriate test type

Step 5: Generate Recommendations

Create specific test suggestions:

• Test function name
• Test scenario
• Example test code
• Parameters to test

Step 6: Calculate Priority

CRITICAL - Must cover immediately:

• Error handling paths
• Security-related code
• Data validation
• Authorization checks

HIGH - Should cover soon:

• Edge cases
• Boundary conditions
• Integration points
• Public API functions

MEDIUM - Good to cover:

• Internal helper functions
• Logging statements
• Configuration parsing

LOW - Optional:

• Debug code
• Development-only paths
• Deprecated functions

Analysis Report Format

# Test Coverage Analysis

## Executive Summary

**Current Coverage:** 75.3%
**Target:** 80%+
**Gap:** 4.7% (23 uncovered lines)
**Status:** ⚠️ Below target

**Breakdown:**
- src/python_modern_template/: 73.2% (18 uncovered lines)
- tests/: 100% (fully covered)

---

## Critical Gaps (MUST FIX)

### 1. Error Handling in validators.py ⚠️ CRITICAL

**File:** src/python_modern_template/validators.py
**Lines:** 45-52 (8 lines)
**Function:** `validate_email()`

**Uncovered Code:**
```python
45: except ValueError as e:
46:     logger.error(f"Email validation failed: {e}")
47:     raise ValidationError(
48:         "Invalid email format"
49:     ) from e
50: except Exception:
51:     logger.critical("Unexpected validation error")
52:     return False

Why Critical: Error handling paths are not tested, could hide bugs

Recommended Test:

def test_validate_email_value_error_handling() -> None:
    """Test email validation handles ValueError correctly."""
    # Arrange
    invalid_email = "not-an-email"

    # Act & Assert
    with pytest.raises(ValidationError) as exc_info:
        validate_email(invalid_email)

    assert "Invalid email format" in str(exc_info.value)
    assert exc_info.value.__cause__ is not None

def test_validate_email_unexpected_error_handling() -> None:
    """Test email validation handles unexpected errors."""
    # Arrange
    # Mock to raise unexpected exception
    with patch('validators.EMAIL_REGEX.match', side_effect=RuntimeError("Unexpected")):
        # Act
        result = validate_email("test@example.com")

        # Assert
        assert result is False

Impact: Covers 8 lines, adds 3.5% coverage

2. Edge Case in parser.py ⚠️ CRITICAL

File: src/python_modern_template/parser.py Lines: 67-70 (4 lines) Function: parse_config()

Uncovered Code:

67: if not config_data:
68:     logger.warning("Empty configuration provided")
69:     return DEFAULT_CONFIG
70:     # Unreachable line removed

Why Critical: Edge case handling not tested

Recommended Test:

def test_parse_config_empty_data() -> None:
    """Test parser handles empty configuration."""
    # Arrange
    empty_config = {}

    # Act
    result = parse_config(empty_config)

    # Assert
    assert result == DEFAULT_CONFIG

def test_parse_config_none_data() -> None:
    """Test parser handles None configuration."""
    # Arrange
    # Act
    result = parse_config(None)

    # Assert
    assert result == DEFAULT_CONFIG

Impact: Covers 4 lines, adds 1.7% coverage

High Priority Gaps

3. Integration Point in api_client.py

File: src/python_modern_template/api_client.py Lines: 112-118 (7 lines) Function: retry_with_backoff()

Uncovered Code:

112: @retry(max_attempts=3, backoff=2.0)
113: def retry_with_backoff(self, operation: Callable) -> Any:
114:     """Retry operation with exponential backoff."""
115:     try:
116:         return operation()
117:     except ConnectionError:
118:         logger.warning("Connection failed, retrying...")

Why High: Integration logic with retry mechanism

Recommended Test:

@pytest.mark.parametrize("attempt,should_succeed", [
    (1, True),  # Succeeds first try
    (2, True),  # Succeeds second try
    (3, True),  # Succeeds third try
    (4, False), # Fails after max attempts
])
def test_retry_