testlint 0.1.0

# Coverage Orchestrator

A multi-language tool that wraps code execution with automated coverage collection and optional upload to your backend.

## Overview

The Coverage Orchestrator automatically instruments your code with coverage tools, runs your tests or application, collects coverage data, and optionally uploads it to your backend - all in one command.

## Supported Languages

| Language | Coverage Tool | Status | Formats |
|----------|--------------|---------|---------|
| **Python** | coverage.py | ✅ Ready | JSON, XML, LCOV, HTML |
| **JavaScript/TypeScript** | Istanbul/NYC | ✅ Ready | JSON, LCOV, HTML, XML (Cobertura) |
| **Java** | JaCoCo | ✅ Ready | XML, HTML |
| **Go** | go test -coverprofile | ✅ Ready | coverage.out, HTML, LCOV* |

*LCOV conversion requires [gcov2lcov](https://github.com/jandelgado/gcov2lcov)

## Installation

```bash
# Build from source
cargo build --release --bin run_with_coverage

# Binary will be at: target/release/run_with_coverage
```

## Quick Start

### Python Example

```bash
# Run pytest with coverage
./run_with_coverage python pytest tests/

# Run a Python script
./run_with_coverage python my_script.py

# Run Python module
./run_with_coverage python -m myapp
```

### JavaScript/TypeScript Example

```bash
# Run JavaScript file with coverage
./run_with_coverage javascript node app.js

# Run Jest tests with coverage
./run_with_coverage javascript npm test

# Run specific test file
./run_with_coverage javascript node tests/api.test.js

# Generate HTML report
./run_with_coverage javascript npm test --format html
```

### Java Example

```bash
# Run Java application with coverage (XML format)
./run_with_coverage java java --format xml -- -cp target/classes com.example.Main

# Run with JUnit tests (Maven)
./run_with_coverage java java --format html -- -cp target/test-classes:target/classes org.junit.runner.JUnitCore com.example.MyTest

# Run JAR file with coverage
./run_with_coverage java java --format xml -- -jar myapp.jar

# Generate HTML report
./run_with_coverage java java --format html -- -cp build/classes Main
```

### Go Example

```bash
# Run Go tests with coverage (HTML format)
./run_with_coverage go go --format html test

# Run tests with coverage.out format
./run_with_coverage go go test

# Run specific package tests
./run_with_coverage go go --format html test -- ./pkg/...

# Generate LCOV format (requires gcov2lcov)
./run_with_coverage go go --format lcov test
```

## Usage

### Basic Syntax

```bash
run_with_coverage <language> <command> [args...] [OPTIONS]
```

### Options

| Option | Description | Default |
|--------|-------------|---------|
| `--output-dir, -o <dir>` | Output directory | `coverage` |
| `--format, -f <format>` | Output format (json, xml, lcov, html) | `json` |
| `--source, -s <path>` | Source path to measure (repeatable) | All |
| `--include <pattern>` | Include pattern (repeatable) | All |
| `--exclude <pattern>` | Exclude pattern (repeatable) | `*/tests/*`, `*/test_*.py` |
| `--no-branch` | Disable branch coverage | Enabled |
| `--upload` | Upload coverage after collection | Disabled |
| `--project <name>` | Project name (for upload) | - |
| `--endpoint <url>` | Upload endpoint | Default backend |
| `--api-key <key>` | API key for upload | From env |
| `--` | Separate tool options from command args | - |

## Examples

### Python Examples

#### Run Tests with Coverage

```bash
# Basic pytest
./run_with_coverage python pytest tests/

# With specific source directory
./run_with_coverage python pytest --source src tests/

# Generate HTML report
./run_with_coverage python pytest --format html

# View report: open coverage/htmlcov/index.html
```

#### Run Application with Coverage

```bash
# Run a script
./run_with_coverage python app.py

# Run a module
./run_with_coverage python -m myapp

# Run with arguments (use -- to separate)
./run_with_coverage python pytest -- -v -s tests/
```

#### Custom Coverage Configuration

```bash
# Exclude specific patterns
./run_with_coverage python pytest \
  --exclude '*/migrations/*' \
  --exclude '*/settings/*' \
  --exclude '*/tests/*'

# Include only specific packages
./run_with_coverage python pytest \
  --source myapp \
  --source shared_lib

# Disable branch coverage (faster)
./run_with_coverage python pytest --no-branch
```

#### Different Output Formats

```bash
# JSON (default) - for upload or programmatic processing
./run_with_coverage python pytest --format json

# XML (Cobertura) - for CI/CD tools
./run_with_coverage python pytest --format xml

# LCOV - for various coverage viewers
./run_with_coverage python pytest --format lcov

# HTML - for human viewing
./run_with_coverage python pytest --format html
```

### JavaScript/TypeScript Examples

#### Run Tests with Coverage

```bash
# Basic npm test
./run_with_coverage javascript npm test

# With specific source directory
./run_with_coverage javascript npm test --source src

# Generate HTML report
./run_with_coverage javascript npm test --format html

# View report: open coverage/index.html
```

#### Run Application with Coverage

```bash
# Run a JavaScript file
./run_with_coverage javascript node app.js

# Run a TypeScript file (requires ts-node)
./run_with_coverage javascript npx ts-node app.ts

# Run with arguments (use -- to separate)
./run_with_coverage javascript node server.js -- --port 3000
```

#### Custom Coverage Configuration

```bash
# Exclude specific patterns
./run_with_coverage javascript npm test \
  --exclude '**/node_modules/**' \
  --exclude '**/*.test.js' \
  --exclude '**/*.spec.js'

# Include only specific packages
./run_with_coverage javascript npm test \
  --source src \
  --source lib

# Disable branch coverage (faster)
./run_with_coverage javascript npm test --no-branch
```

#### Different Output Formats

```bash
# JSON (default) - for upload or programmatic processing
./run_with_coverage javascript npm test --format json

# XML (Cobertura) - for CI/CD tools
./run_with_coverage javascript npm test --format xml

# LCOV - for various coverage viewers
./run_with_coverage javascript npm test --format lcov

# HTML - for human viewing
./run_with_coverage javascript npm test --format html
```

### Java Examples

#### Run Applications with Coverage

```bash
# Basic Java application
./run_with_coverage java java --format xml -- -cp bin Main

# With classpath
./run_with_coverage java java --format xml -- -cp target/classes com.example.App

# Run JAR file
./run_with_coverage java java --format xml -- -jar myapp.jar
```

#### Run Tests with Coverage

```bash
# JUnit tests (Maven project)
./run_with_coverage java java --format html -- \
  -cp target/test-classes:target/classes:~/.m2/repository/junit/junit/4.13.2/junit-4.13.2.jar \
  org.junit.runner.JUnitCore com.example.MyTest

# JUnit 5 tests
./run_with_coverage java java --format xml -- \
  -cp target/test-classes:target/classes \
  -jar junit-platform-console-standalone.jar --scan-classpath

# Gradle project
./run_with_coverage java java --format html -- -cp build/classes/java/main Main
```

#### Different Output Formats

```bash
# XML (default) - Cobertura format for CI/CD tools
./run_with_coverage java java --format xml -- -cp target/classes Main

# HTML - for human viewing
./run_with_coverage java java --format html -- -cp target/classes Main

# Note: JSON and LCOV formats are not supported by JaCoCo
# Use XML format and convert if needed
```

#### Custom Configuration

```bash
# Specify source files for better reports
./run_with_coverage java java --format html --source src/main/java -- \
  -cp target/classes Main

# Disable branch coverage (faster)
./run_with_coverage java java --format xml --no-branch -- \
  -cp target/classes Main

# Specific JaCoCo version
./run_with_coverage java java --format xml --coverage-version 0.8.10 -- \
  -cp target/classes Main
```

### Go Examples

#### Run Tests with Coverage

```bash
# Basic test coverage (coverage.out format)
./run_with_coverage go go test

# Generate HTML coverage report
./run_with_coverage go go test --format html

# Test specific packages
./run_with_coverage go go test ./pkg/... --format html

# Test all packages recursively
./run_with_coverage go go test ./... --format html
```

#### Run Applications with Coverage (Go 1.20+)

**New!** Collect coverage from running Go applications, not just tests!

```bash
# Run a Go program with coverage
./run_with_coverage go go run -cover main.go --format html

# Build and run with coverage
./run_with_coverage go go build -cover -o myapp main.go --format html

# Run a pre-built binary (must be built with -cover)
go build -cover -o myapp main.go
./run_with_coverage go ./myapp --format html

# Run a server with coverage
./run_with_coverage go go run -cover server.go --format html
# Use the server, then Ctrl+C to stop and generate report
```

#### Different Coverage Modes

```bash
# Set mode (default) - does function run?
./run_with_coverage go go --format html test

# Count mode - how many times does each statement run?
# Note: Pass via test flags after --
./run_with_coverage go go test -- -covermode=count

# Atomic mode - for parallel tests
./run_with_coverage go go test -- -covermode=atomic
```

#### Different Output Formats

```bash
# Default coverage.out format - native Go format
./run_with_coverage go go test

# HTML - for human viewing
./run_with_coverage go go --format html test

# LCOV - for CI/CD tools (requires gcov2lcov)
./run_with_coverage go go --format lcov test

# Note: Install gcov2lcov for LCOV conversion
# go install github.com/jandelgado/gcov2lcov@latest
```

#### Custom Configuration

```bash
# Cover specific packages
./run_with_coverage go go --source ./pkg/core,./pkg/utils test

# With verbose output
./run_with_coverage go go --format html test -- -v

# Run with short flag
./run_with_coverage go go test -- -short

# Specific test functions
./run_with_coverage go go test -- -run TestMyFunction
```

### Rust Examples

#### Run Tests with Coverage

```bash
# Basic test coverage with HTML report
./run_with_coverage rust cargo test --format html

# Generate LCOV format
./run_with_coverage rust cargo test --format lcov

# Generate JSON format
./run_with_coverage rust cargo test --format json

# Generate Cobertura XML format (for CI/CD)
./run_with_coverage rust cargo test --format xml
```

#### Run Applications with Coverage

```bash
# Run a Rust application with coverage (cargo run)
./run_with_coverage rust cargo run --format html

# Run with arguments
./run_with_coverage rust cargo run --format html -- --port 8080

# Run examples
./run_with_coverage rust cargo run --example myexample --format html
```

#### Different Output Formats

```bash
# HTML - for human viewing (default)
./run_with_coverage rust cargo test --format html
# View: open coverage/html/index.html

# LCOV - for CI/CD tools and coverage viewers
./run_with_coverage rust cargo test --format lcov

# JSON - for programmatic analysis
./run_with_coverage rust cargo test --format json

# Cobertura XML - for Jenkins, GitLab CI, etc.
./run_with_coverage rust cargo test --format xml
```

#### Custom Configuration

```bash
# Run specific tests
./run_with_coverage rust cargo test test_name --format html

# Run with verbose output
./run_with_coverage rust cargo test --format html -- --nocapture

# Run tests in specific workspace member
./run_with_coverage rust cargo test --source member_name --format html

# Run benchmarks with coverage
./run_with_coverage rust cargo test --format html -- --bench
```

#### Advanced Usage

```bash
# Note: Branch coverage requires nightly toolchain
# To use branch coverage, switch to nightly and run manually:
cargo +nightly llvm-cov test --branch --html

# Or set default toolchain to nightly:
rustup default nightly
./run_with_coverage rust cargo test --format html  # Will use nightly features
```

### C# Examples

#### Run Tests with Coverage

```bash
# Basic test coverage with XML (Cobertura) report
./run_with_coverage csharp dotnet test --format xml

# Generate HTML report (requires ReportGenerator)
./run_with_coverage csharp dotnet test --format html

# Generate LCOV format
./run_with_coverage csharp dotnet test --format lcov

# Generate JSON format
./run_with_coverage csharp dotnet test --format json
```

#### Different Output Formats

```bash
# XML (Cobertura) - native coverlet output
./run_with_coverage csharp dotnet test --format xml
# Output: coverage/cobertura.xml

# HTML - for human viewing (uses ReportGenerator)
./run_with_coverage csharp dotnet test --format html
# View: open coverage/html/index.html

# LCOV - for CI/CD tools (uses ReportGenerator)
./run_with_coverage csharp dotnet test --format lcov
# Output: coverage/lcov.info

# JSON - for programmatic analysis (uses ReportGenerator)
./run_with_coverage csharp dotnet test --format json
# Output: coverage/coverage.json
```

#### Custom Configuration

```bash
# Run specific test project
cd MyProject.Tests
../run_with_coverage csharp dotnet test --format html

# Run tests with filter
./run_with_coverage csharp dotnet test --filter "FullyQualifiedName~Calculator" --format html

# Run tests in specific configuration
./run_with_coverage csharp dotnet test --configuration Release --format html

# Run tests with verbosity
./run_with_coverage csharp dotnet test --verbosity detailed --format xml
```

#### Test Project Setup

For coverage collection to work, your C# test project must include the coverlet.collector package:

```xml
<ItemGroup>
  <PackageReference Include="Microsoft.NET.Test.Sdk" Version="17.6.0" />
  <PackageReference Include="xunit" Version="2.4.2" />
  <PackageReference Include="coverlet.collector" Version="6.0.0">
    <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
    <PrivateAssets>all</PrivateAssets>
  </PackageReference>
</ItemGroup>
```

#### Advanced Usage

```bash
# Multiple test projects (run from solution directory)
./run_with_coverage csharp dotnet test MyProject.sln --format html

# Exclude specific files from coverage
./run_with_coverage csharp dotnet test --format html --exclude "**/Migrations/*"

# Run with no build (faster for repeated runs)
./run_with_coverage csharp dotnet test --no-build --format html

# Collect coverage for integration tests
./run_with_coverage csharp dotnet test IntegrationTests.csproj --format html
```

### Ruby Examples

#### Run Tests with Coverage

```bash
# Basic test coverage with HTML report
./run_with_coverage ruby ruby test_calculator.rb --format html

# Using RSpec (SimpleCov configured in spec_helper.rb)
./run_with_coverage ruby rspec --format html

# Using Rake
./run_with_coverage ruby rake test --format html

# Using Minitest
./run_with_coverage ruby ruby -Ilib:test test/test_*.rb --format html
```

#### Different Output Formats

```bash
# HTML - SimpleCov's default format
./run_with_coverage ruby ruby test_calculator.rb --format html
# View: open coverage/html/index.html

# JSON - SimpleCov .resultset.json
./run_with_coverage ruby ruby test_calculator.rb --format json
# Output: coverage/coverage.json

# LCOV - requires simplecov-lcov gem
./run_with_coverage ruby ruby test_calculator.rb --format lcov
# Output: coverage/lcov.info

# XML (Cobertura) - requires simplecov-cobertura gem
./run_with_coverage ruby ruby test_calculator.rb --format xml
# Output: coverage/cobertura.xml
```

#### Custom Configuration

```bash
# Run with bundle exec
./run_with_coverage ruby bundle exec rspec --format html

# Run specific test file
./run_with_coverage ruby ruby test/models/user_test.rb --format html

# Run with rake and specific task
./run_with_coverage ruby rake test:models --format html

# Run with Guard
./run_with_coverage ruby bundle exec guard --format html
```

#### Test Framework Setup

SimpleCov must be configured in your test helper file. Example for Minitest:

```ruby
# test_helper.rb or test file
require 'simplecov'

# Start SimpleCov if COVERAGE environment variable is set
if ENV['COVERAGE'] || ENV['SIMPLECOV']
  SimpleCov.start do
    add_filter '/test/'
    add_filter '/spec/'
  end
end

require 'minitest/autorun'
# ... rest of your test setup
```

For RSpec, add to spec_helper.rb:

```ruby
# spec/spec_helper.rb
if ENV['COVERAGE'] || ENV['SIMPLECOV']
  require 'simplecov'
  SimpleCov.start 'rails' do  # or just SimpleCov.start for non-Rails
    add_filter '/spec/'
    add_filter '/config/'
  end
end
```

#### Advanced Usage

```bash
# LCOV format (requires simplecov-lcov gem)
gem install simplecov-lcov
./run_with_coverage ruby ruby test_calculator.rb --format lcov

# Cobertura XML (requires simplecov-cobertura gem)
gem install simplecov-cobertura
./run_with_coverage ruby ruby test_calculator.rb --format xml

# Branch coverage (Ruby 2.5+)
# Branch coverage is automatically enabled in Ruby 2.5+ with SimpleCov
./run_with_coverage ruby ruby test_calculator.rb --format html

# Run with specific Ruby version (using rbenv/rvm)
rbenv local 3.2.0
./run_with_coverage ruby ruby test_calculator.rb --format html
```

### C++ Examples

**Important**: C++ coverage requires code compiled with coverage instrumentation.

```bash
# 1. First, compile your C++ code with coverage flags

# For GCC/G++:
g++ --coverage -o myapp main.cpp calculator.cpp
# Or explicitly:
g++ -fprofile-arcs -ftest-coverage -o myapp main.cpp calculator.cpp

# For Clang/Clang++:
clang++ -fprofile-instr-generate -fcoverage-mapping -o myapp main.cpp calculator.cpp

# 2. Run with coverage collection

# Run executable and generate HTML report (using gcov/lcov)
./run_with_coverage cpp ./myapp --format html

# Run tests and generate LCOV format
./run_with_coverage cpp ./test_runner --format lcov

# Run with XML output (Cobertura format)
./run_with_coverage cpp ./myapp --format xml

# Run with JSON output
./run_with_coverage cpp ./myapp --format json

# 3. Different output formats

# HTML report with gcov/lcov (most common)
./run_with_coverage cpp ./test_runner --format html

# LCOV info file for upload or further processing
./run_with_coverage cpp ./myapp --format lcov

# XML for CI integration
./run_with_coverage cpp ./test_runner --format xml --output-dir build/coverage

# 4. Custom configuration

# Specify output directory
./run_with_coverage cpp ./myapp --output-dir coverage/cpp --format html

# Multiple test executables (run separately)
./run_with_coverage cpp ./unit_tests --format lcov
./run_with_coverage cpp ./integration_tests --format lcov

# 5. CMake projects

# Add to CMakeLists.txt:
# set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} --coverage")
# Or for Clang:
# set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -fprofile-instr-generate -fcoverage-mapping")

mkdir build && cd build
cmake -DCMAKE_BUILD_TYPE=Debug ..
make
cd ..
./run_with_coverage cpp ./build/test_runner --format html

# 6. With Google Test

# Compile tests with coverage
g++ --coverage -o test_runner test_*.cpp -lgtest -lgtest_main -pthread

# Run tests with coverage
./run_with_coverage cpp ./test_runner --format html
```

### With Coverage Upload

```bash
# Run and upload to backend
./run_with_coverage python pytest \
  --upload \
  --project my-python-app \
  --endpoint https://coverage.example.com/api \
  --api-key $COVERAGE_API_KEY

# Or use environment variables
export COVERAGE_ENDPOINT=https://coverage.example.com/api
export COVERAGE_API_KEY=your-key-here
./run_with_coverage python pytest --upload --project my-app
```

## Output

### Console Output

```
╔═══════════════════════════════════════╗
║   Coverage Orchestrator              ║
╚═══════════════════════════════════════╝

Language:        Python
Command:         pytest tests/
Output dir:      coverage
Output format:   Json
Branch coverage: true

🐍 Starting Python coverage collection...
📝 Running: coverage run pytest tests/
[test output...]
✓ Command executed successfully
📊 Generating JSON coverage report...
✓ Coverage report generated: coverage/coverage.json

✓ Coverage collection completed successfully!
  Duration: 5 seconds
  Coverage file: coverage/coverage.json

📈 Coverage Summary:
Name                Stmts   Miss Branch BrPart  Cover
------------------------------------------------------
src/app.py            150     10     40      5    91%
src/utils.py           50      2     12      1    95%
src/models.py         200     30     60     10    82%
------------------------------------------------------
TOTAL                 400     42    112     16    88%
```

### Generated Files

**JSON Format:**
```
coverage/
└── coverage.json          # Coverage data in coverage.py JSON format
```

**XML Format:**
```
coverage/
└── coverage.xml           # Cobertura XML format
```

**LCOV Format:**
```
coverage/
└── coverage.info          # LCOV info file
```

**HTML Format:**
```
coverage/
└── htmlcov/
    ├── index.html         # Main coverage report
    ├── status.json        # Coverage metadata
    └── *.html             # Per-file coverage reports
```

## CI/CD Integration

### GitHub Actions

```yaml
name: Test with Coverage

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v3

      - name: Set up Python
        uses: actions/setup-python@v4
        with:
          python-version: '3.11'

      - name: Install dependencies
        run: |
          pip install pytest coverage
          pip install -r requirements.txt

      - name: Install Testlint SDK
        run: |
          curl -L https://github.com/yourusername/testlint-sdk/releases/download/v0.1.0/run_with_coverage -o run_with_coverage
          chmod +x run_with_coverage

      - name: Run tests with coverage
        env:
          COVERAGE_API_KEY: ${{ secrets.COVERAGE_API_KEY }}
          COVERAGE_ENDPOINT: ${{ secrets.COVERAGE_ENDPOINT }}
        run: |
          ./run_with_coverage python pytest tests/ \
            --upload \
            --project ${{ github.repository }} \
            --format json

      - name: Upload coverage artifact
        uses: actions/upload-artifact@v3
        with:
          name: coverage-report
          path: coverage/coverage.json
```

### GitLab CI

```yaml
test:
  image: python:3.11
  stage: test
  script:
    - pip install pytest coverage -r requirements.txt

    # Download orchestrator
    - curl -L https://github.com/yourusername/testlint-sdk/releases/download/v0.1.0/run_with_coverage -o run_with_coverage
    - chmod +x run_with_coverage

    # Run with coverage
    - ./run_with_coverage python pytest tests/
        --upload
        --project $CI_PROJECT_NAME
        --format json
  variables:
    COVERAGE_API_KEY: $COVERAGE_API_KEY
    COVERAGE_ENDPOINT: $COVERAGE_ENDPOINT
  artifacts:
    paths:
      - coverage/coverage.json
    expire_in: 1 week
```

### Jenkins Pipeline

```groovy
pipeline {
    agent any

    environment {
        COVERAGE_API_KEY = credentials('coverage-api-key')
        COVERAGE_ENDPOINT = 'https://coverage.example.com/api'
    }

    stages {
        stage('Test') {
            steps {
                sh '''
                    pip install pytest coverage -r requirements.txt

                    # Download orchestrator
                    curl -L https://github.com/yourusername/testlint-sdk/releases/download/v0.1.0/run_with_coverage -o run_with_coverage
                    chmod +x run_with_coverage

                    # Run with coverage
                    ./run_with_coverage python pytest tests/ \
                        --upload \
                        --project ${JOB_NAME} \
                        --format xml
                '''
            }
        }
    }

    post {
        always {
            archiveArtifacts artifacts: 'coverage/**', allowEmptyArchive: true
        }
    }
}
```

## How It Works

### Python Implementation

1. **Check Dependencies**: Verifies `coverage.py` is installed
2. **Instrument Code**: Runs `coverage run <command>` with configured options
3. **Execute**: Runs your command (tests, script, etc.)
4. **Generate Report**: Creates coverage report in requested format
5. **Upload** (optional): Uploads to backend using Testlint upload tool
6. **Display Summary**: Shows coverage statistics

### Coverage Data Flow

```
┌─────────────┐
│  Your Code  │
└──────┬──────┘
       │
       │ instrumented by coverage.py
       ▼
┌─────────────┐
│   Execute   │
└──────┬──────┘
       │
       │ collect coverage data
       ▼
┌─────────────┐
│ .coverage   │  (internal format)
└──────┬──────┘
       │
       │ convert to requested format
       ▼
┌─────────────┐
│  JSON/XML/  │
│ LCOV/HTML   │
└──────┬──────┘
       │
       │ (optional)
       ▼
┌─────────────┐
│   Upload    │
│  to Backend │
└─────────────┘
```

## Requirements

### Python

```bash
# Required
pip install coverage

# For testing
pip install pytest  # or your test framework
```

Version requirements:
- Python 3.7+
- coverage.py 6.0+

### JavaScript/TypeScript

```bash
# Required (auto-installed if missing)
npm install -g nyc

# For testing
npm install --save-dev jest  # or your test framework
```

Version requirements:
- Node.js v12.0.0+
- NYC 15.0.0+
- Works with Jest, Mocha, AVA, and other test frameworks

**Note:** The orchestrator will automatically install NYC if not found. You can also specify a version:
```bash
./run_with_coverage javascript npm test --coverage-version 15.1.0
```

### Java

```bash
# Required (auto-downloaded if missing)
# JaCoCo agent and CLI are downloaded automatically from Maven Central
```

Version requirements:
- Java 8+ (Java 11+ recommended)
- JaCoCo 0.8.11 (default, configurable)
- Works with Maven, Gradle, and standalone Java applications

**How it works:**
1. Automatically downloads JaCoCo agent and CLI from Maven Central if not found
2. Instruments Java bytecode using `-javaagent` flag
3. Collects coverage data in `.exec` format
4. Generates reports in XML or HTML format

**Note:** The orchestrator will automatically download JaCoCo if not found. You can specify a version:
```bash
./run_with_coverage java java --format xml --coverage-version 0.8.10 -- -cp target/classes Main
```

**Downloaded files location:**
- `~/.jacoco/jacocoagent.jar` - JaCoCo agent for instrumentation
- `~/.jacoco/jacococli.jar` - JaCoCo CLI for report generation

### Go

```bash
# Required (no additional tools needed)
# Go's coverage tools are built-in
```

Version requirements:
- Go 1.11+ for test coverage (`go test -coverprofile`)
- **Go 1.20+ for application coverage** (`go build -cover`, `go run -cover`, GOCOVERDIR)
- Built-in `go test -coverprofile`, `go tool cover`, and `go tool covdata`
- Works with all Go testing frameworks

**How it works (3 modes):**

1. **Test Coverage** (Go 1.11+):
   - Uses `go test -coverprofile` to collect coverage during tests
   - Generates `coverage.out` file in Go's native format
   - Converts to HTML using `go tool cover -html`

2. **Application Coverage with go run** (Go 1.20+):
   - Uses `go run -cover` to instrument and run code
   - Sets `GOCOVERDIR` environment variable
   - Collects coverage data in binary format
   - Uses `go tool covdata` to convert to text format

3. **Pre-built Binary Coverage** (Go 1.20+):
   - Build binary with `go build -cover`
   - Run with `GOCOVERDIR` set
   - Automatically processes coverage files
   - Works with production-like binaries!

**Coverage modes:**
- `set` - did each statement run? (default, fastest)
- `count` - how many times did each statement run?
- `atomic` - like count, but safe for parallel tests

**Optional LCOV conversion:**
```bash
# Install gcov2lcov for LCOV format support
go install github.com/jandelgado/gcov2lcov@latest
```

**Key advantages of Go 1.20+ binary coverage:**
- ✅ Collect coverage from running applications, not just tests
- ✅ Works with web servers, CLI tools, and long-running processes
- ✅ Build once with `-cover`, run multiple times
- ✅ Production-safe (minimal overhead)

### Rust

```bash
# Required (auto-installed if missing)
cargo install cargo-llvm-cov
```

Version requirements:
- Rust 1.60+ (LLVM-based coverage instrumentation)
- cargo-llvm-cov 0.6.0+ (auto-installed)
- Works with stable toolchain (branch coverage requires nightly)

**How it works:**
1. Uses `cargo-llvm-cov` which wraps LLVM's source-based code coverage
2. Automatically installs `cargo-llvm-cov` if not found
3. Instruments code at compile time using LLVM's `-C instrument-coverage`
4. Collects coverage data during test/program execution
5. Generates reports in multiple formats (HTML, LCOV, JSON, Cobertura XML)

**Output formats:**
- **HTML**: Interactive HTML report with source code highlighting
- **LCOV**: Standard format for CI/CD tools (lcov.info)
- **JSON**: Machine-readable format for programmatic analysis
- **Cobertura XML**: XML format for Jenkins, GitLab CI, etc.

**Note on branch coverage:**
Branch coverage requires Rust nightly toolchain. The orchestrator uses stable by default:
```bash
# For branch coverage, switch to nightly first:
rustup default nightly
./run_with_coverage rust cargo test --format html
```

**Advantages of cargo-llvm-cov:**
- ✅ Most accurate coverage (LLVM source-based)
- ✅ Works with cargo test and cargo run
- ✅ Multiple output formats built-in
- ✅ Fast instrumentation and execution
- ✅ Actively maintained

### C#

```bash
# Required
# .NET SDK includes Microsoft.CodeCoverage and coverlet by default
dotnet --version

# Optional (for format conversion)
dotnet tool install -g dotnet-reportgenerator-globaltool
```

Version requirements:
- .NET SDK 6.0+ (recommended, .NET Core 3.1+ minimum)
- coverlet.collector (included in test project)
- ReportGenerator (auto-installed for HTML/LCOV/JSON formats)

**How it works:**
1. Uses `dotnet test --collect:"XPlat Code Coverage"` with coverlet
2. Collects coverage data during test execution
3. Generates Cobertura XML format natively
4. Uses ReportGenerator for HTML, LCOV, and JSON conversion
5. Automatically installs ReportGenerator if needed for format conversion

**Test Project Setup:**
Your C# test project must include coverlet.collector:
```xml
<ItemGroup>
  <PackageReference Include="Microsoft.NET.Test.Sdk" Version="17.6.0" />
  <PackageReference Include="coverlet.collector" Version="6.0.0">
    <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
    <PrivateAssets>all</PrivateAssets>
  </PackageReference>
</ItemGroup>
```

**Output formats:**
- **XML (Cobertura)**: Native coverlet output, no conversion needed
- **HTML**: Uses ReportGenerator to convert from Cobertura
- **LCOV**: Uses ReportGenerator for standard CI/CD format
- **JSON**: Uses ReportGenerator for programmatic analysis

**Note on ReportGenerator:**
ReportGenerator is automatically installed as a global .NET tool if not found. Manual installation:
```bash
dotnet tool install -g dotnet-reportgenerator-globaltool
```

**Advantages of dotnet test + coverlet:**
- ✅ Built into .NET SDK (Microsoft.CodeCoverage)
- ✅ Cross-platform (Windows, macOS, Linux)
- ✅ Works with all .NET test frameworks (xUnit, NUnit, MSTest)
- ✅ Cobertura XML native output
- ✅ ReportGenerator provides multiple format conversions
- ✅ Actively maintained by .NET Foundation

### Ruby

```bash
# Required
gem install simplecov

# Optional (for additional formats)
gem install simplecov-lcov        # For LCOV format
gem install simplecov-cobertura   # For Cobertura XML format

# Or use Bundler
bundle add simplecov --group development,test
```

Version requirements:
- Ruby 2.5+ (recommended, 2.3+ minimum)
- SimpleCov 0.22+ (auto-installed if missing)
- simplecov-lcov for LCOV format (optional)
- simplecov-cobertura for XML format (optional)

**How it works:**
1. SimpleCov uses Ruby's built-in Coverage library
2. Instruments code automatically when required
3. Collects coverage data during test execution
4. Generates HTML reports by default
5. Supports additional formatters for LCOV and Cobertura XML

**Test Framework Integration:**
SimpleCov must be required in your test helper file before any application code:

```ruby
# test_helper.rb, spec_helper.rb, or test file
require 'simplecov'

if ENV['COVERAGE'] || ENV['SIMPLECOV']
  SimpleCov.start do
    add_filter '/test/'
    add_filter '/spec/'
  end
end
```

**Output formats:**
- **HTML**: Interactive HTML report (default SimpleCov formatter)
- **JSON**: SimpleCov's .resultset.json file with coverage data
- **LCOV**: Requires simplecov-lcov gem for CI/CD integration
- **XML (Cobertura)**: Requires simplecov-cobertura gem for Jenkins, GitLab

**Branch Coverage:**
Branch coverage is automatically enabled in Ruby 2.5+ with SimpleCov. The Coverage library in Ruby 2.5+ includes branch coverage support by default.

**Note on Formatters:**
The orchestrator will:
- Use HTML formatter by default (built-in)
- For JSON format, uses SimpleCov's .resultset.json
- For LCOV/XML, checks for required gems and provides helpful error messages if missing

**Advantages of SimpleCov:**
- ✅ Built on Ruby's stdlib Coverage library
- ✅ Fast and efficient (minimal performance impact)
- ✅ HTML reports with detailed visualizations
- ✅ Branch coverage support (Ruby 2.5+)
- ✅ Multiple formatter support via gems
- ✅ Works with all Ruby test frameworks (Minitest, RSpec, Test::Unit)
- ✅ Actively maintained by the Ruby community

### C++

**Important**: C++ coverage requires code compiled with coverage instrumentation flags.

**GCC/G++ Coverage (gcov/lcov):**
```bash
# Install lcov (optional but recommended for HTML reports)
# Ubuntu/Debian
sudo apt-get install lcov

# macOS
brew install lcov

# Fedora/RHEL
sudo dnf install lcov
```

**LLVM/Clang Coverage (llvm-cov):**
```bash
# Usually installed with LLVM/Clang
# Ubuntu/Debian
sudo apt-get install clang llvm

# macOS (via Xcode or Homebrew)
brew install llvm

# Fedora/RHEL
sudo dnf install clang llvm
```

Version requirements:
- GCC 4.8+ or Clang 3.4+ (for coverage support)
- lcov 1.10+ (optional, for HTML reports)
- LLVM 3.4+ (for llvm-cov)

**How it works:**

1. **Compilation**: Code must be compiled with coverage flags
   - GCC: `--coverage` or `-fprofile-arcs -ftest-coverage`
   - Clang: `-fprofile-instr-generate -fcoverage-mapping`

2. **Execution**: Running the program generates coverage data
   - GCC: Creates .gcda files alongside .gcno files
   - Clang: Creates .profraw files

3. **Processing**: The tool detects and processes coverage data
   - Detects gcov data (.gcda files) or llvm-cov data (.profraw files)
   - Routes to appropriate processing function

4. **Report Generation**:
   - **HTML**: Uses lcov + genhtml (GCC) or llvm-cov show (Clang)
   - **LCOV**: Uses lcov --capture (GCC) or llvm-cov export (Clang)
   - **XML**: Converts LCOV to Cobertura XML
   - **JSON**: Custom conversion from coverage data

**Compilation Examples:**

```bash
# GCC/G++ - Compile with coverage
g++ --coverage -o myapp main.cpp calculator.cpp

# Clang/Clang++ - Compile with coverage
clang++ -fprofile-instr-generate -fcoverage-mapping -o myapp main.cpp calculator.cpp

# CMake project
# Add to CMakeLists.txt:
set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} --coverage")

# Or for Clang:
set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -fprofile-instr-generate -fcoverage-mapping")
```

**Output Formats:**
- **HTML**: Full visual report with line-by-line coverage (requires lcov or llvm-cov)
- **LCOV**: Industry-standard format (.info file) for CI/CD
- **XML**: Cobertura format for Jenkins, GitLab CI, etc.
- **JSON**: Machine-readable format for custom processing

**Coverage Tools Used:**
- **gcov**: GCC's built-in coverage tool (always available with GCC)
- **lcov**: Frontend for gcov (optional, for better reports)
- **genhtml**: Generates HTML from lcov.info (part of lcov)
- **llvm-cov**: LLVM's coverage tool (for Clang)
- **llvm-profdata**: Merges .profraw files (part of LLVM)

**Note on Coverage Data:**
The orchestrator automatically detects which toolchain was used:
- If .gcda files exist → Uses gcov/lcov workflow
- If .profraw or .profdata files exist → Uses llvm-cov workflow
- Provides clear error messages if coverage data is not found

**Advantages of gcov/lcov:**
- ✅ Built into GCC (no extra installation for gcov)
- ✅ Widely used and well-documented
- ✅ Excellent HTML reports via genhtml
- ✅ LCOV format supported by most CI/CD platforms
- ✅ Works with CMake, Make, and other build systems
- ✅ Branch coverage support

**Advantages of llvm-cov:**
- ✅ Built into LLVM/Clang
- ✅ Source-based coverage (more accurate)
- ✅ Modern, actively developed
- ✅ JSON export support
- ✅ Efficient for large codebases
- ✅ Branch and region coverage

## Comparison with Other Tools

| Feature | Coverage Orchestrator | coverage.py | tox | pytest-cov |
|---------|----------------------|-------------|-----|------------|
| Multi-language | ✅ Yes | ❌ Python only | ✅ Yes | ❌ Python only |
| Auto-upload | ✅ Yes | ❌ No | ❌ No | ❌ No |
| Unified CLI | ✅ Yes | ❌ No | Partial | ❌ No |
| Branch coverage | ✅ Yes | ✅ Yes | ✅ Yes | ✅ Yes |
| HTML reports | ✅ Yes | ✅ Yes | ✅ Yes | ✅ Yes |
| CI-friendly | ✅ Yes | ✅ Yes | ✅ Yes | ✅ Yes |

## Troubleshooting

### "coverage.py not found"

```bash
# Install coverage.py
pip install coverage

# Verify installation
coverage --version
```

### "Command failed"

The orchestrator runs your command as-is. If it fails:

1. Test the command works without coverage:
   ```bash
   python pytest tests/  # Does this work?
   ```

2. Then add coverage:
   ```bash
   ./run_with_coverage python pytest tests/
   ```

### No coverage data collected

- Check that you're specifying the correct source paths
- Ensure your code is actually being executed
- Try without `--source` to measure everything

### Permission errors

```bash
# Make sure the tool is executable
chmod +x run_with_coverage

# Check output directory permissions
mkdir -p coverage
chmod 755 coverage
```

## Advanced Usage

### Custom Coverage Configuration

Create `.coveragerc` in your project root:

```ini
[run]
source = src
omit =
    */tests/*
    */migrations/*
    */venv/*

[report]
precision = 2
show_missing = True

[html]
directory = coverage/htmlcov
```

The orchestrator will automatically use this configuration.

### Parallel Coverage Collection

```bash
# Run multiple test suites in parallel
./run_with_coverage python pytest tests/unit/ &
./run_with_coverage python pytest tests/integration/ &
wait

# Combine coverage data
coverage combine
coverage report
```

### Coverage with Docker

```dockerfile
FROM python:3.11-slim

WORKDIR /app

# Install dependencies
COPY requirements.txt .
RUN pip install -r requirements.txt coverage

# Copy orchestrator
COPY run_with_coverage /usr/local/bin/
RUN chmod +x /usr/local/bin/run_with_coverage

# Copy code
COPY . .

# Run with coverage
CMD ["run_with_coverage", "python", "pytest", "tests/", "--upload"]
```

## Future Enhancements

- ✅ Python support (coverage.py)
- 🚧 Java support (JaCoCo)
- 🚧 JavaScript support (Istanbul/NYC)
- 🚧 Go support (go test -coverprofile)
- 🚧 Differential coverage (compare with base branch)
- 🚧 Coverage trending over time
- 🚧 Slack/Discord notifications
- 🚧 Pull request comments with coverage changes

## Contributing

To add support for a new language:

1. Implement the `run_<language>_coverage()` method in `test_orchestrator.rs`
2. Add format generation methods for that language
3. Update documentation
4. Add tests

## License

MIT License - See LICENSE file for details