skycov

skycov

A coverage reporter for Starlark code that generates reports in multiple formats including text, JSON, Cobertura XML, and LCOV. Integrates with CI systems and code coverage platforms.

Caution

Coverage collection requires starlark-go-x instrumentation, which is not yet available upstream. Currently, skycov processes coverage data files generated by skytest or demonstrates the report formats with demo data.

Installation

go install github.com/albertocavalcante/sky/cmd/skycov@latest

Usage

# Display text coverage report
skycov coverage.json

# Generate Cobertura XML for CI
skycov -format=cobertura -o coverage.xml coverage.json

# Generate LCOV for IDE integration
skycov -format=lcov -o coverage.lcov coverage.json

# Fail if coverage is below threshold
skycov -min=80 coverage.json

# Verbose output with line details
skycov -v coverage.json

# Demo mode (no input file)
skycov

Flags

Flag	Description
-format	Output format: text, json, cobertura, lcov (default: text)
-o	Output file (default: stdout)
-min	Minimum coverage percentage (fail if below)
-source	Source directory for relative paths in reports
-v	Verbose output
-version	Print version and exit

Coverage Workflow

1. Collect Coverage Data

Run tests with coverage enabled (requires starlark-go-x):

# Generate coverage data during tests
skytest -coverage -coverprofile=coverage.json .

2. Generate Reports

Process coverage data with skycov:

# Human-readable summary
skycov coverage.json

# CI-friendly formats
skycov -format=cobertura -o coverage.xml coverage.json
skycov -format=lcov -o coverage.lcov coverage.json

3. Enforce Coverage Thresholds

# Fail build if coverage drops below 80%
skycov -min=80 coverage.json

Output Formats

Text Format (Default)

Human-readable summary:

$ skycov coverage.json
Coverage Report
===============

File                  Lines    Covered  Percentage
----                  -----    -------  ----------
src/math.star         20       20       100.0%
src/utils.star        10       7        70.0%
src/legacy.star       15       2        13.3%
----                  -----    -------  ----------
Total                 45       29       64.4%

With -v flag, shows uncovered lines:

$ skycov -v coverage.json
src/utils.star: 70.0% (7/10 lines)
  Missing lines: 8, 9, 10

src/legacy.star: 13.3% (2/15 lines)
  Missing lines: 3-15

JSON Format

Machine-readable JSON for tooling:

$ skycov -format=json coverage.json

{
  "files": {
    "src/math.star": {
      "lines": {
        "1": 5,
        "2": 5,
        "3": 10
      }
    },
    "src/utils.star": {
      "lines": {
        "1": 3,
        "2": 3,
        "8": 0,
        "9": 0
      }
    }
  },
  "total_lines": 45,
  "covered_lines": 29,
  "percentage": 64.44
}

Cobertura XML Format

For Jenkins, GitLab, and other CI systems:

$ skycov -format=cobertura -o coverage.xml coverage.json

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE coverage SYSTEM "http://cobertura.sourceforge.net/xml/coverage-04.dtd">
<coverage line-rate="0.644" branch-rate="0" version="1.0" timestamp="1234567890">
  <packages>
    <package name="src" line-rate="0.644">
      <classes>
        <class name="math.star" filename="src/math.star" line-rate="1.0">
          <lines>
            <line number="1" hits="5"/>
            <line number="2" hits="5"/>
          </lines>
        </class>
      </classes>
    </package>
  </packages>
</coverage>

LCOV Format

For genhtml and IDE integration:

$ skycov -format=lcov -o coverage.lcov coverage.json

TN:
SF:src/math.star
DA:1,5
DA:2,5
DA:3,10
LF:20
LH:20
end_of_record
SF:src/utils.star
DA:1,3
DA:2,3
DA:8,0
DA:9,0
LF:10
LH:7
end_of_record

Generate HTML report with genhtml:

skycov -format=lcov -o coverage.lcov coverage.json
genhtml coverage.lcov -o coverage-html/
open coverage-html/index.html

CI Integration

GitHub Actions

- name: Run tests with coverage
  run: |
    skytest -coverage -coverprofile=coverage.json -r .

- name: Generate coverage report
  run: |
    skycov -format=cobertura -o coverage.xml coverage.json

- name: Check coverage threshold
  run: |
    skycov -min=80 coverage.json

- name: Upload coverage to Codecov
  uses: codecov/codecov-action@v3
  with:
    files: coverage.xml

GitLab CI

test:
  script:
    - skytest -coverage -coverprofile=coverage.json -r .
    - skycov -format=cobertura -o coverage.xml coverage.json
  artifacts:
    reports:
      coverage_report:
        coverage_format: cobertura
        path: coverage.xml
  coverage: '/Total.*(\d+\.\d+)%/'

Jenkins

stage('Test') {
    steps {
        sh 'skytest -coverage -coverprofile=coverage.json -r .'
        sh 'skycov -format=cobertura -o coverage.xml coverage.json'
    }
    post {
        always {
            cobertura coberturaReportFile: 'coverage.xml'
        }
    }
}

Coverage Data Format

skycov reads coverage data in JSON format generated by skytest:

{
  "files": {
    "path/to/file.star": {
      "lines": {
        "1": 5,
        "2": 3,
        "10": 0
      }
    }
  },
  "total_lines": 100,
  "covered_lines": 75,
  "percentage": 75.0
}

The lines object maps line numbers (as strings) to hit counts:

• > 0: Line was executed that many times
• 0: Line is executable but was not executed

Exit Codes

Code	Meaning
0	Success (coverage meets minimum if specified)
1	Coverage below minimum threshold
2	Error (file not found, parse error, etc.)

Examples

Combine with skytest

# Run tests and generate all report formats
skytest -coverage -coverprofile=coverage.json -r .
skycov coverage.json                                    # Terminal summary
skycov -format=json -o coverage-report.json coverage.json  # JSON
skycov -format=cobertura -o coverage.xml coverage.json  # CI
skycov -format=lcov -o coverage.lcov coverage.json      # HTML gen

Enforce Coverage in CI

ci-coverage.sh

#!/bin/bash
MIN_COVERAGE=80

skytest -coverage -coverprofile=coverage.json -r .

# Generate reports
skycov -format=cobertura -o coverage.xml coverage.json

# Check threshold
if ! skycov -min=${MIN_COVERAGE} coverage.json; then
  echo "Coverage is below ${MIN_COVERAGE}%"
  exit 1
fi

Local Development Workflow

# Quick coverage check during development
skytest -coverage . && skycov coverage.json

# Detailed view of uncovered lines
skycov -v coverage.json | grep "Missing"

# Generate HTML report for detailed analysis
skycov -format=lcov -o cov.lcov coverage.json
genhtml cov.lcov -o coverage-html
open coverage-html/index.html

Compare Coverage Between Runs

# Save baseline coverage
skycov -format=json coverage.json | jq '.percentage' > baseline.txt

# After changes, compare
skycov -format=json coverage.json | jq '.percentage' > current.txt
baseline=$(cat baseline.txt)
current=$(cat current.txt)

if (( $(echo "$current < $baseline" | bc -l) )); then
  echo "Warning: Coverage decreased from $baseline% to $current%"
fi

Future: starlark-go-x Integration

Once starlark-go-x supports coverage instrumentation, the workflow will be:

// In your Go code using starlark-go-x
thread := &starlark.Thread{Name: "test"}
collector := coverage.NewCollector()
thread.SetCoverageCollector(collector)

// Execute Starlark code...

// Get coverage report
report := collector.Report()

The collector hooks required in starlark-go-x:

• BeforeExec(filename, line) - Called before each statement
• EnterFunction(filename, name, line) - Called when entering a function
• Thread.SetCoverageCollector(c) - Set the collector for a thread

See the starlark-go-x repository for instrumentation progress.