evizi-kit 1.0.0

package/kits/shared/skills/increase-unit-test-coverage/SKILL.md

@@ -0,0 +1,117 @@
+---
+name: increase-unit-test-coverage
+description: Systematically increase unit test coverage for files with low coverage. Works with any repository by reading configuration from `.documents-design/project.config.json`. Use this skill whenever the user mentions test coverage, coverage reports, low coverage percentages, writing unit tests for uncovered files, improving test quality, or anything related to test coverage improvement — even if they don't explicitly say "coverage skill". Also triggers for requests like "write tests for files that need them", "get coverage above 90%", or "which files need more tests".
+---
+
+# Increase Unit Test Coverage
+
+Improve unit test coverage by analyzing coverage reports and writing targeted, meaningful tests for under-covered files. The goal is not just hitting a coverage number — it's building confidence that the code works correctly. Coverage is the measurement tool, but test quality is the real objective.
+
+## Configuration
+
+All project-specific settings live in `.documents-design/project.config.json` under the `unitTestCoverage` key. Read this file first — it tells you how the project runs tests, where test files live, what to exclude, and what framework/library to use.
+
+Key fields: `testCommand`, `coverageReportPath`, `threshold`, `testDirectory`, `testFilePattern`, `testingFramework`, `testingLibrary`, `excludePatterns`, `excludeDirectories`, `reportTopN`.
+
+If the config file doesn't exist, ask the user for these details before proceeding.
+
+## Workflow
+
+### Step 1: Generate a Coverage Baseline
+
+Run the project's test command with coverage enabled (from `config.testCommand`):
+
+```bash
+npm test -- --coverage
+```
+
+This produces a `coverage-summary.json` at the path specified in `config.coverageReportPath`.
+
+### Step 2: Filter and Prioritize Files
+
+Run the bundled filter script. It reads config automatically and produces a concise, prioritized markdown report:
+
+```bash
+python <this-skill-directory>/scripts/filter_low_coverage.py
+```
+
+CLI overrides are available (`-t` for threshold, `-n` for top-N files, `--full` for all files) but defaults from config are usually sufficient.
+
+Read the generated report (at `config.outputReportPath`, default `low-coverage-report.md`). It groups files by severity:
+- **🔴 Zero** (0%) — no tests at all
+- **🟠 Critical** (<50%) — severely under-tested
+- **🟡 Moderate** (50–70%) — partial coverage with significant gaps
+- **🟢 Minor** (70–threshold%) — close but missing edge cases
+
+### Step 3: Understand Before Writing
+
+For each target file, do this research before writing a single test:
+
+1. **Read the source file thoroughly.** Understand what the module does, its public API, its side effects, and its dependencies. You cannot write a good test for code you don't understand.
+
+2. **Read existing tests** (if any) in `config.testDirectory`. Understand what's already covered and what patterns the project follows — naming conventions, file structure, import style, mocking approach. Consistency with existing tests matters because it reduces cognitive load for the team maintaining them.
+
+3. **Identify the coverage gaps.** Look at which lines, branches, and functions are uncovered. The coverage report tells you *where* the gaps are; the source code tells you *why* they matter. Focus on:
+   - Untested public functions and methods
+   - Conditional branches (if/else, switch, ternary) — these are where bugs hide
+   - Error handling paths — often the most impactful to test because failures in error handling cascade
+   - Edge cases at boundaries (empty arrays, null inputs, zero values)
+
+### Step 4: Write Meaningful Tests
+
+Work through files in priority order (🔴 → 🟠 → 🟡 → 🟢).
+
+**What makes a test meaningful:**
+
+- **Test behavior, not implementation.** Ask "what should this code *do*?" not "what lines does it execute?" A test that verifies the right output for a given input survives refactoring. A test that asserts internal method calls breaks when you clean up the code.
+
+- **Each test should have a clear reason to exist.** If you can't explain what bug this test would catch, it's probably not worth writing. Coverage-gaming tests (calling a function without asserting anything meaningful) create a false sense of security.
+
+- **Mock at the boundary, not everywhere.** Mock external dependencies (API calls, database, file system, third-party services) but avoid mocking internal modules unless absolutely necessary. Over-mocking makes tests brittle and disconnected from reality.
+
+- **Name tests descriptively.** `it('should return empty array when user has no orders')` is far more useful than `it('test case 3')`. When a test fails, the name should immediately tell you what broke.
+
+**For zero-coverage files:** Create a new test file following `config.testFilePattern` and `config.testingFramework`. Start with the happy path, then add error cases and edge cases.
+
+**For partially-covered files:** Add targeted tests for the specific uncovered branches and functions. Don't rewrite existing tests unless they're broken.
+
+### Step 5: Verify and Iterate
+
+After writing tests for each file:
+
+1. **Run tests** to confirm they pass:
+   ```bash
+   npm test
+   ```
+
+2. **Re-run coverage** to verify improvement:
+   ```bash
+   npm test -- --coverage
+   ```
+
+3. **Re-run the filter script** to update the report and see progress:
+   ```bash
+   python <this-skill-directory>/scripts/filter_low_coverage.py
+   ```
+
+4. If coverage didn't improve as expected, check whether your tests are actually exercising the uncovered paths. A common mistake is testing a wrapper function without triggering the branch inside it.
+
+5. **Move to the next file** in priority order. Complete one file fully before starting the next — partial work across many files is harder to track and review.
+
+Continue until the target threshold from config is met, or until remaining uncovered files have legitimate reasons for lower coverage (pure type files, generated code, etc.).
+
+## Handling Tricky Scenarios
+
+- **Heavily coupled code** that's hard to test often signals a design issue. Write the best tests you can, but note to the user that the module may benefit from refactoring to improve testability.
+- **Files with complex state management** (Redux stores, context providers): test the logic separately from the UI. Reducer tests and selector tests are simpler and more valuable than full integration tests.
+- **Async code**: make sure tests properly await promises and handle both resolved and rejected paths.
+- **Files the config excludes** (CSS modules, type definitions, constants): skip these. They're excluded for a reason — they either can't be meaningfully tested or the effort isn't worth it.
+
+## Communicating Progress
+
+When working through multiple files, provide brief updates after each file:
+- What file was improved
+- Coverage before → after
+- Any issues encountered
+
+This helps the user track progress and decide when to stop.

package/kits/shared/skills/increase-unit-test-coverage/scripts/filter_low_coverage.py

@@ -0,0 +1,447 @@
+#!/usr/bin/env python3
+"""
+Filter files with low test coverage from Jest coverage-summary.json report.
+Generates a markdown report of files that need increased test coverage.
+
+Works with multiple IDEs - automatically detects configuration from:
+  - .documents-design/project.config.json
+
+Automatically excludes files that don't need unit tests:
+- CSS files: *.css.ts, *.css.tsx, *.css, *.less, *.scss, *.sass
+- Configuration files: constants.ts, urls.ts, languageList.ts, countryList.ts, 
+                       countryPhoneCodes.ts, gdpr.ts, selectedColumns.ts
+- Type definition files: types.ts, interfaces.ts
+- Model files: Files in models/ directory (pure TypeScript interfaces)
+
+All exclusion patterns can be customized via .documents-design/project.config.json
+"""
+
+import json
+import sys
+import os
+from pathlib import Path
+from typing import Dict, List, Tuple, Optional
+
+
+def find_config_file() -> Optional[Path]:
+    """
+    Find project.config.json in .documents-design/ directory.
+    
+    Searches in order:
+    1. .documents-design/project.config.json
+    
+    Searches up to 5 directory levels from current location.
+    """
+    search_paths = [
+        '.documents-design/project.config.json',
+    ]
+    
+    current = Path.cwd()
+    for _ in range(5):  # Search up to 5 levels
+        for search_path in search_paths:
+            config_path = current / search_path
+            if config_path.exists():
+                return config_path
+        current = current.parent
+    
+    return None
+
+
+def find_skill_directory() -> str:
+    """
+    Find the skills directory based on IDE configuration.
+    
+    Returns the appropriate path prefix:
+    - .cursor/skills/ (Cursor)
+    - .github/copilot/skills/ (GitHub Copilot)
+    - .agent/skills/ (Generic/Antigravity)
+    - .claude/skills/ (Claude Code)
+    """
+    current = Path.cwd()
+    for _ in range(5):
+        if (current / '.documents-design').exists():
+            return '.documents-design/'
+        current = current.parent
+    
+    return '.documents-design/'  # Default fallback
+
+
+def load_project_config(workspace_root: Optional[str] = None) -> Optional[Dict]:
+    """Load configuration from project.config.json if it exists."""
+    if workspace_root:
+        # Try .documents-design location in workspace root
+        search_paths = [
+            Path(workspace_root) / '.documents-design' / 'project.config.json',
+        ]
+        
+        config_path = None
+        for path in search_paths:
+            if path.exists():
+                config_path = path
+                break
+        
+        if not config_path:
+            return None
+    else:
+        # Auto-detect config file
+        config_path = find_config_file()
+        if not config_path:
+            return None
+    
+    try:
+        with open(config_path, 'r') as f:
+            config = json.load(f)
+            return config.get('unitTestCoverage', {})
+    except (json.JSONDecodeError, IOError):
+        return None
+
+
+def load_coverage_report(report_path: str) -> Dict:
+    """Load the Jest coverage-summary.json file."""
+    try:
+        with open(report_path, 'r') as f:
+            return json.load(f)
+    except FileNotFoundError:
+        print(f"Error: Coverage report not found at {report_path}", file=sys.stderr)
+        sys.exit(1)
+    except json.JSONDecodeError as e:
+        print(f"Error: Invalid JSON in coverage report: {e}", file=sys.stderr)
+        sys.exit(1)
+
+
+def calculate_average_coverage(file_data: Dict) -> float:
+    """Calculate average coverage percentage across all metrics."""
+    metrics = ['lines', 'statements', 'functions', 'branches']
+    percentages = [file_data.get(metric, {}).get('pct', 0) for metric in metrics]
+    return sum(percentages) / len(percentages)
+
+
+def filter_low_coverage_files(
+    coverage_data: Dict,
+    threshold: float = 90.0,
+    workspace_root: str = None,
+    exclude_patterns: List[str] = None,
+    exclude_directories: List[str] = None
+) -> List[Tuple[str, Dict]]:
+    """
+    Filter files with coverage below threshold.
+    
+    Args:
+        coverage_data: Coverage data from coverage-summary.json
+        threshold: Coverage percentage threshold (default 90%)
+        workspace_root: Workspace root path to make file paths relative
+        exclude_patterns: List of file patterns to exclude (e.g., ['*.css.ts', 'constants.ts'])
+        exclude_directories: List of directory names to exclude (e.g., ['models', 'types'])
+        
+    Returns:
+        List of tuples: (file_path, coverage_metrics)
+    """
+    low_coverage_files = []
+    
+    # Default exclude patterns if none provided
+    if exclude_patterns is None:
+        exclude_patterns = [
+            '*.css.ts', '*.css.tsx', '*.css', '*.less', '*.scss', '*.sass',
+            'constants.ts', 'constants.js',
+            'urls.ts', 'urls.js',
+            'languageList.ts', 'languageList.js',
+            'countryList.ts', 'countryList.js',
+            'countryPhoneCodes.ts', 'countryPhoneCodes.js',
+            'gdpr.ts', 'gdpr.js',
+            'selectedColumns.ts', 'selectedColumns.js',
+            'types.ts', 'types.js',
+            'interfaces.ts', 'interfaces.js'
+        ]
+    
+    if exclude_directories is None:
+        exclude_directories = ['models']
+    
+    for file_path, metrics in coverage_data.items():
+        # Skip the 'total' summary entry
+        if file_path == 'total':
+            continue
+        
+        # Check exclude patterns
+        should_exclude = False
+        for pattern in exclude_patterns:
+            if pattern.startswith('*.'):
+                # Extension pattern
+                ext = pattern[1:]  # Remove the *
+                if file_path.endswith(ext):
+                    should_exclude = True
+                    break
+            else:
+                # Exact filename pattern
+                if file_path.endswith(f'/{pattern}') or file_path.endswith(f'\\{pattern}'):
+                    should_exclude = True
+                    break
+        
+        if should_exclude:
+            continue
+        
+        # Check exclude directories
+        for dir_name in exclude_directories:
+            if f'/{dir_name}/' in file_path or f'\\{dir_name}\\' in file_path:
+                should_exclude = True
+                break
+        
+        if should_exclude:
+            continue
+            
+        # Calculate average coverage
+        avg_coverage = calculate_average_coverage(metrics)
+        
+        # Filter files below threshold
+        if avg_coverage < threshold:
+            # Make path relative to workspace if provided
+            display_path = file_path
+            if workspace_root:
+                try:
+                    display_path = str(Path(file_path).relative_to(workspace_root))
+                except ValueError:
+                    pass  # Keep absolute path if not relative to workspace
+                    
+            low_coverage_files.append((display_path, metrics, avg_coverage))
+    
+    # Sort by average coverage (lowest first)
+    low_coverage_files.sort(key=lambda x: x[2])
+    
+    return low_coverage_files
+
+
+def generate_markdown_report(
+    low_coverage_files: List[Tuple[str, Dict, float]],
+    threshold: float,
+    output_path: str,
+    top_n: int = 30,
+    show_full: bool = False
+) -> None:
+    """Generate a markdown report of files with low coverage."""
+    
+    # Group by severity
+    zero_coverage = [f for f in low_coverage_files if f[2] == 0]
+    critical = [f for f in low_coverage_files if 0 < f[2] < 50]
+    moderate = [f for f in low_coverage_files if 50 <= f[2] < 70]
+    minor = [f for f in low_coverage_files if 70 <= f[2] < threshold]
+    
+    with open(output_path, 'w') as f:
+        f.write("# Unit Test Coverage Report - Low Coverage Files\n\n")
+        f.write(f"Files with coverage below **{threshold}%** threshold.\n\n")
+        
+        if not low_coverage_files:
+            f.write("✅ All files meet the coverage threshold!\n")
+            return
+        
+        # Summary statistics
+        f.write("## Summary Statistics\n\n")
+        f.write(f"**Total files needing attention:** {len(low_coverage_files)}\n\n")
+        f.write("| Severity | Count | Coverage Range |\n")
+        f.write("|----------|-------|----------------|\n")
+        f.write(f"| 🔴 Zero | {len(zero_coverage)} | 0% |\n")
+        f.write(f"| 🟠 Critical | {len(critical)} | <50% |\n")
+        f.write(f"| 🟡 Moderate | {len(moderate)} | 50-70% |\n")
+        f.write(f"| 🟢 Minor | {len(minor)} | 70-{threshold}% |\n\n")
+        
+        # Top priority files
+        files_to_show = low_coverage_files if show_full else low_coverage_files[:top_n]
+        
+        f.write(f"## Top {min(top_n, len(low_coverage_files))} Priority Files\n\n")
+        f.write("*Files with the lowest coverage - start here*\n\n")
+        f.write("| File | Avg Coverage | Lines | Statements | Functions | Branches |\n")
+        f.write("|------|--------------|-------|------------|-----------|----------|\n")
+        
+        for file_path, metrics, avg_cov in files_to_show:
+            lines_pct = metrics.get('lines', {}).get('pct', 0)
+            stmts_pct = metrics.get('statements', {}).get('pct', 0)
+            funcs_pct = metrics.get('functions', {}).get('pct', 0)
+            branch_pct = metrics.get('branches', {}).get('pct', 0)
+            
+            # Status icon
+            if avg_cov == 0:
+                status = "🔴"
+            elif avg_cov < 50:
+                status = "🟠"
+            elif avg_cov < 70:
+                status = "🟡"
+            else:
+                status = "🟢"
+            
+            f.write(f"| {status} `{file_path}` | **{avg_cov:.1f}%** | {lines_pct:.1f}% | {stmts_pct:.1f}% | {funcs_pct:.1f}% | {branch_pct:.1f}% |\n")
+        
+        if not show_full and len(low_coverage_files) > top_n:
+            f.write(f"\n*...and {len(low_coverage_files) - top_n} more files*\n")
+        
+        # Grouped breakdown by severity (condensed)
+        f.write("\n## Files by Severity\n\n")
+        
+        if zero_coverage:
+            f.write(f"### 🔴 Zero Coverage ({len(zero_coverage)} files)\n\n")
+            f.write("**Priority: CRITICAL** - These files have no tests\n\n")
+            show_count = min(10, len(zero_coverage)) if not show_full else len(zero_coverage)
+            for i, (file_path, metrics, _) in enumerate(zero_coverage[:show_count]):
+                lines_total = metrics.get('lines', {}).get('total', 0)
+                funcs_total = metrics.get('functions', {}).get('total', 0)
+                f.write(f"{i+1}. `{file_path}` ({lines_total} lines, {funcs_total} functions)\n")
+            if not show_full and len(zero_coverage) > show_count:
+                f.write(f"\n*...and {len(zero_coverage) - show_count} more files*\n")
+            f.write("\n")
+        
+        if critical:
+            f.write(f"### 🟠 Critical (<50% coverage, {len(critical)} files)\n\n")
+            show_count = min(10, len(critical)) if not show_full else len(critical)
+            for i, (file_path, metrics, avg_cov) in enumerate(critical[:show_count]):
+                f.write(f"{i+1}. `{file_path}` - **{avg_cov:.1f}%**\n")
+            if not show_full and len(critical) > show_count:
+                f.write(f"\n*...and {len(critical) - show_count} more files*\n")
+            f.write("\n")
+        
+        if moderate:
+            f.write(f"### 🟡 Moderate (50-70% coverage, {len(moderate)} files)\n\n")
+            show_count = min(10, len(moderate)) if not show_full else len(moderate)
+            for i, (file_path, metrics, avg_cov) in enumerate(moderate[:show_count]):
+                f.write(f"{i+1}. `{file_path}` - **{avg_cov:.1f}%**\n")
+            if not show_full and len(moderate) > show_count:
+                f.write(f"\n*...and {len(moderate) - show_count} more files*\n")
+            f.write("\n")
+        
+        if minor:
+            f.write(f"### 🟢 Minor (70-{threshold}% coverage, {len(minor)} files)\n\n")
+            show_count = min(10, len(minor)) if not show_full else len(minor)
+            for i, (file_path, metrics, avg_cov) in enumerate(minor[:show_count]):
+                f.write(f"{i+1}. `{file_path}` - **{avg_cov:.1f}%**\n")
+            if not show_full and len(minor) > show_count:
+                f.write(f"\n*...and {len(minor) - show_count} more files*\n")
+            f.write("\n")
+        
+        # Next steps
+        f.write("## Recommended Action Plan\n\n")
+        f.write("1. **Start with 🔴 Zero Coverage files** - Write new tests from scratch\n")
+        f.write("2. **Address 🟠 Critical files** - Significantly expand test coverage\n")
+        f.write("3. **Improve 🟡 Moderate files** - Add missing test cases\n")
+        f.write("4. **Polish 🟢 Minor files** - Final push to achieve target coverage\n\n")
+        
+        # Footer
+        f.write("---\n\n")
+        if not show_full and len(low_coverage_files) > top_n:
+            f.write("💡 **Tip:** Run with `--full` flag to see all files\n\n")
+        f.write("*Report generated from Jest coverage-summary.json*\n")
+
+
+def main():
+    """Main entry point."""
+    import argparse
+    
+    parser = argparse.ArgumentParser(
+        description='Filter files with low test coverage from Jest coverage report'
+    )
+    parser.add_argument(
+        'coverage_report',
+        nargs='?',
+        help='Path to coverage-summary.json file (auto-detected from config if omitted)'
+    )
+    parser.add_argument(
+        '-o', '--output',
+        help='Output markdown file path (default from config or low-coverage-report.md)'
+    )
+    parser.add_argument(
+        '-t', '--threshold',
+        type=float,
+        help='Coverage threshold percentage (default from config or 90.0)'
+    )
+    parser.add_argument(
+        '-w', '--workspace',
+        help='Workspace root path for relative file paths (auto-detected if omitted)'
+    )
+    parser.add_argument(
+        '--config',
+        help='Path to project.config.json file (default: .documents-design/project.config.json)'
+    )
+    parser.add_argument(
+        '-n', '--top-n',
+        type=int,
+        help='Number of top priority files to show (default from config or 30)'
+    )
+    parser.add_argument(
+        '--full',
+        action='store_true',
+        help='Show all files instead of just top N (default from config or False)'
+    )
+    
+    args = parser.parse_args()
+    
+    # Try to load configuration
+    workspace_root = args.workspace or os.getcwd()
+    
+    # Detect config file location
+    config_path = None
+    if workspace_root:
+        search_paths = [
+            Path(workspace_root) / '.documents-design' / 'project.config.json',
+        ]
+        for path in search_paths:
+            if path.exists():
+                config_path = path
+                break
+    else:
+        config_path = find_config_file()
+    
+    config = load_project_config(workspace_root)
+    
+    if config and config.get('enabled', True):
+        print(f"📋 Loaded configuration from {config_path}")
+        
+        # Use config values as defaults, CLI args override
+        coverage_report = args.coverage_report or config.get('coverageReportPath')
+        output_path = args.output or config.get('outputReportPath', 'low-coverage-report.md')
+        threshold = args.threshold if args.threshold is not None else config.get('threshold', 90.0)
+        top_n = args.top_n if args.top_n is not None else config.get('reportTopN', 30)
+        show_full = args.full or config.get('reportShowFullList', False)
+        exclude_patterns = config.get('excludePatterns', None)
+        exclude_directories = config.get('excludeDirectories', None)
+    else:
+        # No config or config disabled, use CLI args or defaults
+        if not args.coverage_report:
+            print("Error: coverage_report argument required when no config is available", file=sys.stderr)
+            print("", file=sys.stderr)
+            print("Create configuration at:", file=sys.stderr)
+            print("  - .documents-design/project.config.json", file=sys.stderr)
+            print("", file=sys.stderr)
+            print("Or provide coverage report path explicitly", file=sys.stderr)
+            sys.exit(1)
+        
+        coverage_report = args.coverage_report
+        output_path = args.output or 'low-coverage-report.md'
+        threshold = args.threshold if args.threshold is not None else 90.0
+        top_n = args.top_n if args.top_n is not None else 30
+        show_full = args.full
+        exclude_patterns = None
+        exclude_directories = None
+    
+    print(f"📊 Loading coverage report: {coverage_report}")
+    coverage_data = load_coverage_report(coverage_report)
+    
+    print(f"🔍 Filtering files with coverage < {threshold}%")
+    low_coverage_files = filter_low_coverage_files(
+        coverage_data,
+        threshold,
+        workspace_root,
+        exclude_patterns,
+        exclude_directories
+    )
+    
+    report_mode = "all files" if show_full else f"top {top_n} files"
+    print(f"📝 Generating markdown report ({report_mode}): {output_path}")
+    generate_markdown_report(low_coverage_files, threshold, output_path, top_n, show_full)
+    
+    print(f"\n✅ Report generated successfully!")
+    print(f"   Found {len(low_coverage_files)} files below {threshold}% coverage")
+    print(f"   Report saved to: {output_path}")
+    
+    if config:
+        excluded_count = len(exclude_patterns or [])
+        excluded_dirs = len(exclude_directories or [])
+        print(f"   Excluded patterns: {excluded_count} file patterns, {excluded_dirs} directories")
+
+
+if __name__ == '__main__':
+    main()