analyze-coverage

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):

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:

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:

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

# 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):

pytest --cov={package} --cov-report=term-missing --cov-report=json --cov-branch

If specific test directories were detected:

pytest {test_dirs} --cov={package} --cov-report=term-missing --cov-report=json --cov-branch

TypeScript (Vitest with coverage):

npx vi