Code Quality Guardian

# Code Quality Guardian

An intelligent code quality analysis and improvement skill that combines white-box (code coverage) and black-box (requirement traceability) testing to ensure comprehensive software quality.

## Overview

Code Quality Guardian automatically analyzes your codebase for quality issues, collaborates with you to devise improvement strategies, generates missing tests, and validates improvements through automated testing.

## Core Capabilities

1. **Dual-Dimension Analysis**
   - **White-box**: Code coverage analysis (line, branch, function)
   - **Black-box**: Requirement traceability verification
   
2. **Interactive Collaboration**
   - Identifies quality gaps and presents findings
   - Proposes fix strategies with pros/cons
   - Collaborates with user to select optimal approach
   
3. **Automated Test Generation**
   - Creates missing test cases for uncovered code
   - Generates requirement-linked tests for traceability
   - Follows language-specific testing best practices
   
4. **Validation & Reporting**
   - Runs tests to verify improvements
   - Generates comprehensive quality reports
   - Tracks before/after metrics

## Workflow

### Phase 1: Detection

When user requests quality analysis:

1. **Detect Project Type**
   - Scan for configuration files (pytest, jest, pom.xml, etc.)
   - Identify programming language and test framework
   - Locate source and test directories

2. **Run Coverage Analysis**
   ```bash
   # Python example
   pytest --cov=src --cov-report=json --cov-report=term tests/
   
   # JavaScript example
   npm test -- --coverage --coverageReporters=json
   
   # Java example
   mvn clean test jacoco:report
   ```

3. **Analyze Requirements Coverage**
   - Extract requirement tags from tests (e.g., `@pytest.mark.req("REQ-001")`)
   - Compare against requirements document/comments
   - Identify untested requirements

### Phase 2: Interactive Diagnosis

Present findings in structured format:

```
Quality Analysis Report
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

WHITE-BOX COVERAGE
├─ Line Coverage:      72% (580/805 lines)
├─ Branch Coverage:    65% (78/120 branches)
└─ Function Coverage:  88% (44/50 functions)

BLACK-BOX TRACEABILITY
├─ Requirements Total:  15
├─ Requirements Tested: 11
└─ Missing Coverage:    REQ-007, REQ-012, REQ-014, REQ-015

CRITICAL GAPS IDENTIFIED
1. Error Handling Module (0% coverage)
2. Edge Case Validation (32% coverage)
3. Bulk Operations (REQ-007 untested)
```

Then ask:

> I've identified several quality gaps. Which area should we prioritize?
>
> A) Error Handling Module (highest risk, 0% coverage)
> B) Edge Case Validation (moderate coverage gaps)
> C) Requirement Coverage (4 requirements untested)
> D) Show detailed analysis first

### Phase 3: Strategy Collaboration

For selected area, present fix options:

```
Fix Strategy for: Error Handling Module
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Option A: Comprehensive Test Suite
✓ Pros: Complete coverage, catches edge cases
✗ Cons: 45-60 min to implement
📝 Scope: 8 test cases covering all error paths

Option B: Critical Path Only
✓ Pros: Quick (15-20 min), covers main scenarios
✗ Cons: Leaves some edge cases untested
📝 Scope: 3 test cases for primary errors

Option C: Risk-Based Approach
✓ Pros: Balanced coverage (30 min), focuses on high-risk areas
✗ Cons: Requires priority assessment
📝 Scope: 5 test cases for critical error scenarios

Your choice? (A/B/C, or suggest alternative)
```

### Phase 4: Automated Fixing

Once strategy is confirmed:

1. **Generate Test Files**
   ```python
   # Example: tests/test_error_handling.py
   import pytest
   from src.module import function_under_test
   
   @pytest.mark.req("REQ-007")
   def test_invalid_input_handling():
       """Verify graceful handling of invalid inputs"""
       with pytest.raises(ValueError, match="Invalid input"):
           function_under_test(invalid_data)
   
   def test_network_error_recovery():
       """Ensure system recovers from network failures"""
       # Test implementation...
   ```

2. **Run Generated Tests**
   - Execute new test suite
   - Capture results and coverage metrics
   - Fix any test failures iteratively

3. **Validate Improvement**
   ```bash
   pytest --cov=src --cov-report=term-missing tests/
   ```

### Phase 5: Reporting

Generate comprehensive report:

```
Quality Improvement Summary
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

BEFORE → AFTER
├─ Line Coverage:      72% → 92% (+20%)
├─ Branch Coverage:    65% → 88% (+23%)
└─ Function Coverage:  88% → 96% (+8%)

REQUIREMENT COVERAGE
├─ Requirements Tested: 11 → 15 (+4)
└─ Coverage Rate:       73% → 100% (+27%)

TESTS ADDED
├─ test_error_handling.py       (5 tests)
├─ test_edge_cases.py           (3 tests)
└─ test_req_007_bulk_ops.py     (2 tests)

NEXT STEPS
• All critical gaps addressed ✓
• Consider adding performance tests
• Review test maintainability
```

## Supported Languages & Tools

| Language   | Coverage Tool        | Test Framework       |
|------------|---------------------|----------------------|
| Python     | pytest-cov          | pytest               |
| JavaScript | Istanbul/c8         | Jest/Mocha           |
| TypeScript | Istanbul            | Jest/Vitest          |
| Java       | JaCoCo              | JUnit                |
| Go         | go test -cover      | testing package      |
| C#         | Coverlet            | xUnit/NUnit          |

## Configuration

Create `.quality-guardian.json` in project root:

```json
{
  "coverage": {
    "thresholds": {
      "line": 80,
      "branch": 75,
      "function": 90
    },
    "exclude": ["**/migrations/**", "**/tests/**"]
  },
  "requirements": {
    "source": "docs/requirements.md",
    "tagFormat": "@req\\(\"([A-Z]+-\\d+)\"\\)"
  },
  "autoFix": {
    "maxTestsPerFile": 10,
    "generateMocks": true,
    "preferredStyle": "AAA"
  }
}
```

## Usage Examples

### Basic Analysis

```
User: Analyze code quality for this project