analyze-coverage

What this skill does

# Analyze Coverage Skill

Analyze test coverage for any project by running real coverage tools, parsing results into structured reports, and identifying gaps with actionable recommendations. Optionally maps coverage against spec acceptance criteria to find untested requirements.

**CRITICAL: Complete ALL 6 phases.** The workflow is not complete until Phase 6: Suggest Next Steps is finished. After completing each phase, immediately proceed to the next phase without waiting for user prompts.

## Core Principles

1. **Real coverage data** -- Run actual coverage tools (pytest-cov, istanbul/c8) via Bash. Never estimate or guess coverage percentages.
2. **Standalone operation** -- This skill works on any project. It does not require the SDD pipeline, specs, or any other skill to function.
3. **Actionable output** -- Every coverage gap should include a specific suggestion for what test to write, not just a percentage.
4. **Graceful degradation** -- If coverage tools are not installed, detect and inform the user with install commands. If a spec is invalid, skip spec mapping and proceed with coverage-only analysis.

## AskUserQuestion is MANDATORY

**IMPORTANT**: You MUST use the `AskUserQuestion` tool for ALL questions to the user. Never ask questions through regular text output.

- Clarifying questions about project structure -> AskUserQuestion
- Framework/tool selection -> AskUserQuestion
- Threshold confirmation -> AskUserQuestion

Text output should only be used for presenting information, summaries, reports, and progress updates.

**NEVER do this** (asking via text output):
```
Which package should I measure coverage for?
1. src/
2. lib/
```

**ALWAYS do this** (using AskUserQuestion tool):
```yaml
AskUserQuestion:
  questions:
    - header: "Coverage Target"
      question: "Which package or directory should coverage be measured for?"
      options:
        - label: "src/"
          description: "Main source directory"
        - label: "lib/"
          description: "Library directory"
      multiSelect: false
```

---

## Phase 1: Detect Environment

**Goal:** Auto-detect the project's test framework, coverage tool, and source package.

### Parse Arguments

Analyze `$ARGUMENTS` to extract optional parameters:

- **Project path**: Directory to analyze (default: current working directory)
- **`--spec <path>`**: Spec file for acceptance criteria mapping
- **`--threshold <percentage>`**: Coverage threshold override (default: 80%)

### Detect Project Type

Determine the project type by checking for language-specific files:

**Python detection (check in order):**
1. `pyproject.toml` exists -> Python project
2. `setup.py` or `setup.cfg` exists -> Python project
3. `requirements.txt` exists -> Python project
4. `*.py` files in source directories -> Python project

**TypeScript/JavaScript detection (check in order):**
1. `package.json` exists -> TypeScript/JavaScript project
2. `tsconfig.json` exists -> TypeScript project
3. `*.ts` or `*.tsx` files in source directories -> TypeScript project

If both Python and TypeScript indicators are found, prefer the one with more signals. If ambiguous, prompt the user:

```yaml
AskUserQuestion:
  questions:
    - header: "Project Type"
      question: "Both Python and TypeScript project files were detected. Which should be analyzed for coverage?"
      options:
        - label: "Python"
          description: "Analyze Python coverage with pytest-cov"
        - label: "TypeScript"
          description: "Analyze TypeScript coverage with istanbul/c8"
      multiSelect: false
```

### Detect Coverage Tool

Read the coverage patterns reference for framework-specific detection:
```
Read: ${CLAUDE_PLUGIN_ROOT}/skills/analyze-coverage/references/coverage-patterns.md
```

**Python: pytest-cov**

Check for `pytest-cov` in the following locations (stop at first match):

1. `pyproject.toml` -> look for "pytest-cov" in dependencies
2. `requirements.txt` / `requirements-dev.txt` -> look for "pytest-cov" line
3. `setup.py` / `setup.cfg` -> look for "pytest-cov" in install_requires or extras_require
4. Run `pip list 2>/dev/null | grep -i pytest-cov`

**TypeScript: istanbul / c8**

Check `package.json` for coverage tool packages:

1. `devDependencies` -> look for `c8`, `@vitest/coverage-v8`, `@vitest/coverage-istanbul`
2. `devDependencies` -> look for `jest` (Jest has built-in istanbul coverage)
3. Check if c8 binary is available: `npx c8 --version 2>/dev/null`

### Detect Test Runner

**Python:**
- `pyproject.toml` with `[tool.pytest.ini_options]` -> pytest
- `pytest.ini` or `conftest.py` exists -> pytest

**TypeScript:**
- `vitest.config.*` exists -> Vitest
- `jest.config.*` exists -> Jest
- `package.json` with `vitest` in devDependencies -> Vitest
- `package.json` with `jest` in devDependencies -> Jest

### Detect Source Package

Identify the main source package/directory to measure coverage for:

**Python:**
1. Check `pyproject.toml` `[tool.coverage.run] source` setting
2. Check `.coveragerc` `[run] source` setting
3. Look for directories containing `__init__.py`
4. Exclude `tests/`, `test/`, `docs/`, `.venv/`, `venv/`
5. If multiple candidates, prompt the user

**TypeScript:**
1. Check `vitest.config.*` or `jest.config.*` for `collectCoverageFrom` or `coverage.include`
2. Default to `src/` if it exists
3. If `src/` does not exist, look for the main directory from `package.json` `main` or `module` field
4. If ambiguous, prompt the user

### Detect Test Directories

Locate test files and directories:

**Python:**
```bash
# Find test directories
find . -type d -name "tests" -o -name "test" | head -10
# Find test files
find . -name "test_*.py" -o -name "*_test.py" | head -20
```

**TypeScript:**
```bash
# Find test files
find . -name "*.test.ts" -o -name "*.spec.ts" -o -name "*.test.tsx" -o -name "*.spec.tsx" | grep -v node_modules | head -20
```

### Handle Missing Coverage Tool

If the coverage tool is not detected:

**Python -- pytest-cov not found:**
```
Coverage tool not detected.

pytest-cov is not installed. Install it with:

  pip install pytest-cov

Or add "pytest-cov" to your dev dependencies in pyproject.toml:

  [project.optional-dependencies]
  dev = ["pytest-cov"]
```

**TypeScript -- no coverage tool found:**

For Vitest projects:
```
Coverage tool not detected.

Install the Vitest coverage provider:

  npm install -D @vitest/coverage-v8
```

For Jest projects:
```
Jest includes istanbul coverage by default. No additional installation required.
Run with: npx jest --coverage
```

After presenting the install command, stop the workflow. Do not attempt to run coverage without the tool installed.

### Handle No Test Files

If no test files are found in the project:

1. Report: `No test files detected. Coverage: 0%`
2. Recommend: `Use /generate-tests to create an initial test suite based on your source code`
3. If a spec path was provided, report ALL acceptance criteria as **untested**
4. Skip Phase 2 (Run Coverage) and Phase 3 (Parse Results) -- proceed directly to Phase 4 (Analyze Gaps) if spec provided, or Phase 5 (Generate Report) if no spec

### Handle No Source Files

If no source files are found in the project path:

```
ERROR: No source files found in {project-path}.

The directory exists but contains no files matching supported extensions
(.py, .ts, .tsx, .js, .jsx).

Check that the project path is correct, or specify it explicitly:
  /analyze-coverage /path/to/project
```

Stop the workflow after this error.

---

## Phase 2: Run Coverage

**Goal:** Execute the coverage tool and capture output.

### Build Coverage Command

Based on the detected environment, construct the appropriate coverage command.

**Python (pytest-cov):**
```bash
pytest --cov={package} --cov-report=term-missing --cov-report=json --cov-branch
```

If specific test directories were detected:
```bash
pytest {test_dirs} --cov={package} --cov-report=term-missing --cov-report=json --cov-branch
```

**TypeScript (Vitest with coverage):**
```bash
npx v