coverage-analyzer

What this skill does

# 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

```bash
# Generate detailed coverage analysis
analyze test coverage
```

**Output:** Comprehensive report with gaps and recommendations

### Find Critical Gaps

```bash
# Focus on critical uncovered code
show critical coverage gaps
```

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

### Get Test Suggestions

```bash
# 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

```bash
# See coverage over time
show coverage trend for last month
```

**Output:** Graph showing coverage changes

## Step-by-Step Analysis Process

### Step 1: Run Coverage

```bash
# 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:

```bash
# 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

```markdown
# 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:**
```python
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("[email protected]")

        # 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:**
```python
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:**
```python
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:**
```python
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:**
```python
@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