go-coverage

If the setup command fails, manually configure:

1. Go to Settings → Environments → github-pages
2. Under Deployment branches, select "Selected branches and tags"
3. Add these deployment branch rules:
   • master (main deployments)
   • gh-pages (GitHub Pages default)
   • *, */*, */*/*, */*/*/*, */*/*/*/*, */*/*/*/*/* (all branches for PR-specific reports)
4. Save changes and verify in workflow runs

Create a .go-coverage.json config file:

{
  "coverage": {
    "threshold": 80.0,
    "exclude_paths": ["vendor/", "test/"],
    "exclude_files": ["*.pb.go", "*_gen.go"]
  },
  "badge": {
    "style": "flat",
    "logo": "go"
  },
  "report": {
    "title": "My Project Coverage",
    "theme": "dark"
  },
  "history": {
    "enabled": true,
    "retention_days": 90
  }
}

• Zero External Dependencies – Complete coverage system that runs entirely in your CI/CD pipeline with no third-party services required.
• GitHub Pages Integration – Automatic deployment of coverage reports, badges, and dashboards with branch-specific and PR-specific deployments.
• Advanced Coverage Analysis – Parse Go coverage profiles with support for path exclusions, file pattern exclusions, and threshold enforcement.
• Professional Badge Generation – SVG coverage badges with customizable styles, colors, logos, and themes that update automatically.
• Rich HTML Reports – Beautiful, responsive coverage dashboards with detailed file-level analysis and interactive visualizations.
• Coverage History & Trends – Track coverage changes over time with retention policies, trend analysis, and historical comparisons.
• Smart GitHub Integration – Automated PR comments with coverage analysis, commit status checks, and diff-based coverage reporting.
• Multi-Branch Support – Separate coverage tracking for different branches with automatic main branch detection and PR context handling.
• Comprehensive CLI Tool – Six powerful commands (complete, comment, parse, history, setup-pages, upgrade) for all coverage operations.
• Highly Configurable – JSON-based configuration for thresholds, exclusions, badge styling, report themes, and integration settings.
• Enterprise Ready – Built with security, performance, and scalability in mind for production environments.
• Self-Contained Deployment – Everything runs in your repository's .github folder with no external service dependencies or accounts required.

This project uses goreleaser for streamlined binary and library deployment to GitHub. To get started, install it via:

brew install goreleaser

The release process is defined in the .goreleaser.yml configuration file.

Then create and push a new Git tag using:

magex version:bump push=true bump=patch

This process ensures consistent, repeatable releases with properly versioned artifacts and citation metadata.

View all build commands

magex help

All workflows are driven by modular configuration in .github/env/ — no YAML editing required.

View all workflows and the control center →

To update all dependencies (Go modules, linters, and related tools), run:

magex deps:update

This command ensures all dependencies are brought up to date in a single step, including Go modules and any tools managed by MAGE-X. It is the recommended way to keep your development environment and CI in sync with the latest versions.

Set up the Go-Pre-commit System to run the same formatting, linting, and tests defined in AGENTS.md before every commit:

go install github.com/mrz1836/go-pre-commit/cmd/go-pre-commit@latest
go-pre-commit install

The system is configured via .github/env/ and provides 17x faster execution than traditional Python-based pre-commit hooks. See the complete documentation for details.

The coverage system includes comprehensive fuzz tests for critical functions to ensure robustness and security:

Available Fuzz Tests

Running Fuzz Tests

# Run specific fuzz tests
go test -fuzz=FuzzBuildGitHubCommitURL -fuzztime=10s ./internal/urlutil/
go test -fuzz=FuzzGetColorForPercentage -fuzztime=10s ./internal/badge/
go test -fuzz=FuzzParseStatementSimple -fuzztime=10s ./internal/parser/

# Run all fuzz tests (via MAGE-X)
magex test-fuzz

Fuzz Test Features

• ✅ Comprehensive Input Coverage: Valid inputs, edge cases, malformed data
• ✅ Security Testing: Path traversal, XSS, injection attempts, null bytes
• ✅ Panic Prevention: Never panics on any input
• ✅ Unicode Support: Proper UTF-8 handling and validation
• ✅ Performance Testing: Long inputs, memory efficiency

Benchmark Results

Performance Characteristics

• Concurrent Operations: All critical paths support concurrent execution
• Memory Efficiency: Streaming parsers for large files
• Caching: Template compilation and static asset caching
• Optimization: Profile-guided optimizations for hot paths

Running Benchmarks

# Run all benchmarks
magex bench

# Run specific component benchmarks
go test -bench=. ./internal/parser/...
go test -bench=. ./internal/badge/...
go test -bench=. ./internal/analytics/...
go test -bench=. ./internal/history/...
go test -bench=. ./internal/analysis/...

# Run with memory profiling
go test -bench=. -benchmem ./...

# Generate benchmark comparison
go test -bench=. -count=5 ./... | tee new.txt
benchstat old.txt new.txt

Real-World Metrics

• ⚡ CI/CD Integration: Adds < 2 seconds to your workflow
• 📊 Memory Efficient: Peak usage under 10MB for large repositories
• 🚀 GitHub Pages: Deploy coverage reports in under 30 seconds
• 📈 Scalable: Tested with repositories containing 100,000+ lines of code

Performance benchmarks measured on GitHub Actions runners (10-core CPU) with production Go projects.

Sub-Agents Overview

This project leverages a comprehensive team of specialized Claude Code sub-agents to manage development, testing, and deployment workflows. Each agent has specific expertise and can work independently or collaboratively to maintain the go-coverage system.

Available Sub-Agents

Using Sub-Agents

Sub-agents can be invoked in two ways:

1. Automatic Delegation: Claude Code automatically delegates tasks based on context and the agent's specialization
2. Explicit Invocation: Request a specific agent by name:

   > Use the code-reviewer agent to review my recent changes
   > Have the debugger investigate this test failure
   > Ask the coverage-analyzer to generate a new report
   

Agent Coordination

Sub-agents work together cohesively:

• go-test-runner → triggers coverage-analyzer after successful tests
• code-reviewer → invokes go-linter for style issues
• dependency-manager → calls security-scanner for vulnerability checks

Configuration

Sub-agent configurations are stored in .claude/agents/ and can be customized:

• Edit agent prompts to adjust behavior
• Modify tool access for security constraints
• Add project-specific instructions

Benefits

• Specialized Expertise: Each agent excels in its domain
• Parallel Processing: Multiple agents can work simultaneously
• Isolated Contexts: Agents maintain separate contexts to prevent pollution
• Consistent Workflows: Standardized approaches across the team
• Improved Efficiency: Faster task completion with focused agents

For detailed information about each sub-agent's capabilities and configuration, see the individual agent files in .claude/agents/.

Claude Code Commands

The project includes 20 powerful slash commands that orchestrate our sub-agents for common development tasks. These commands provide quick access to complex workflows:

Quick Examples

/fix              # Automatically fix test failures and linter issues
/test parser.go   # Create comprehensive tests for a file
/coverage         # Analyze and improve test coverage to 90%+
/pr-ready        # Make your code PR-ready with all checks
/review          # Get comprehensive code review
/secure          # Run security vulnerability scan
/health          # Complete project health check

Command Categories

• Quality & Testing: /fix, /test, /coverage, /dedupe
• Documentation: /doc-update, /doc-review, /explain, /prd
• Development: /review, /optimize, /refactor
• Maintenance: /deps, /secure, /health, /clean
• Workflow: /pr-ready, /debug-ci, /release-prep, /benchmark, /commit

See the complete Claude Code Commands Reference for detailed usage, examples, and best practices.