If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/simplecov-ruby/simplecov shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across all four use cases

• Last commit 2d ago
• 6 active contributors
• MIT licensed
• CI configured
• Tests present
• ⚠ Single-maintainer risk — top contributor 87% of recent commits

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live simplecov-ruby/simplecov repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/simplecov-ruby/simplecov.

What it runs against: a local clone of simplecov-ruby/simplecov — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in simplecov-ruby/simplecov | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 32 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of simplecov-ruby/simplecov. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/simplecov-ruby/simplecov.git
#   cd simplecov
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of simplecov-ruby/simplecov and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "simplecov-ruby/simplecov(\\.git)?\\b" \\
  && ok "origin remote is simplecov-ruby/simplecov" \\
  || miss "origin remote is not simplecov-ruby/simplecov (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "lib/simplecov.rb" \\
  && ok "lib/simplecov.rb" \\
  || miss "missing critical file: lib/simplecov.rb"
test -f "lib/simplecov/configuration.rb" \\
  && ok "lib/simplecov/configuration.rb" \\
  || miss "missing critical file: lib/simplecov/configuration.rb"
test -f "lib/simplecov/combine/results_combiner.rb" \\
  && ok "lib/simplecov/combine/results_combiner.rb" \\
  || miss "missing critical file: lib/simplecov/combine/results_combiner.rb"
test -f "lib/simplecov-html.rb" \\
  && ok "lib/simplecov-html.rb" \\
  || miss "missing critical file: lib/simplecov-html.rb"
test -f "lib/simplecov/defaults.rb" \\
  && ok "lib/simplecov/defaults.rb" \\
  || miss "missing critical file: lib/simplecov/defaults.rb"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 32 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~2d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/simplecov-ruby/simplecov"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

SimpleCov is a Ruby code coverage analysis tool that wraps Ruby's built-in Coverage library to provide filtering, grouping, merging, and formatting of coverage results across multiple test suites. It automatically caches and merges coverage data (via the lib/simplecov core) and generates HTML reports through the separate simplecov-html formatter, enabling developers to see comprehensive coverage including RSpec, Cucumber, Minitest, and parallel test execution. Monolithic gem structure: lib/simplecov/ contains the core engine (configuration, result processing, merging), lib/simplecov/formatters/ holds output formatters, features/ contains Gherkin acceptance tests, benchmarks/ for performance tracking. Separate simplecov-html gem handles HTML rendering. Configuration system (SimpleCov::Configuration) is central; examples in features/ show typical setup patterns.

Ruby developers and CI/CD engineers who need to track code coverage across heterogeneous test suites (unit tests, feature tests, integration tests running in parallel) and want automated reporting without manual coverage result coordination. Teams using RSpec, Cucumber, Minitest, or parallel_tests with Rails or pure Ruby projects.

Production-ready and actively maintained. The project has comprehensive CI via GitHub Actions (stable, unstable, lint, typecheck workflows), extensive Gherkin feature tests (50+ .feature files in features/), and RSpec coverage. Recent activity visible in CHANGELOG.md and multiple maintained workflows suggest continuous development. Badge presence (Gem Version, Build Status, Maintainability) indicates established gem published to RubyGems.

Standard open source risks apply.

Active maintenance on coverage merging, branch coverage support (branch_coverage.feature), subprocess tracking (config_enable_for_subprocesses.feature), JSON formatter enhancements (config_json_formatter.feature), and parallel test integration (parallel_tests.feature). TypeScript compilation for assets (esbuild, tsc in package.json) suggests recent frontend tooling work for the HTML formatter interop.

git clone https://github.com/simplecov-ruby/simplecov.git
cd simplecov
bundle install
bundle exec rspec
bundle exec cucumber

Daily commands:

bundle exec rake  # runs default Rake task (likely tests)
bundle exec rspec  # run RSpec suite
bundle exec cucumber  # run Gherkin features
npm run build  # compiles TypeScript/assets via rake assets:compile
npm run typecheck  # runs TypeScript type checking

• lib/simplecov.rb — Main entry point and public API for SimpleCov; all integrations start here and every contributor must understand the initialization flow
• lib/simplecov/configuration.rb — Core configuration DSL that defines all coverage behavior; critical for understanding how users customize SimpleCov
• lib/simplecov/combine/results_combiner.rb — Orchestrates merging of coverage data across parallel test runs; fundamental to SimpleCov's multi-process support
• lib/simplecov-html.rb — HTML formatter and report generation; the primary user-facing output and critical for report quality
• lib/simplecov/defaults.rb — Default configuration and formatters; establishes SimpleCov's out-of-box behavior that all contributors should know
• lib/simplecov/directive.rb — Handles nocov comments and skipping code blocks; core to line-coverage accuracy and user annotations

• **** — undefined

Add a new configuration option

1. Define the configuration method in Configuration#defaults or Configuration#configure block (lib/simplecov/configuration.rb)
2. Add the option to SimpleCov::Configuration instance methods (e.g. add_filter, add_group) (lib/simplecov/configuration.rb)
3. Update defaults if it affects initialization behavior (lib/simplecov/defaults.rb)
4. Write a feature test validating the configuration works end-to-end (features/config_*.feature)

Add a new formatter

1. Create a new class implementing SimpleCov::Formatter interface (result method) (lib/simplecov/*.rb (new file))
2. Register formatter in SimpleCov::Configuration#add_formatter or defaults (lib/simplecov/defaults.rb)
3. Add Cucumber step to verify formatter output (features/step_definitions/simplecov_steps.rb)
4. Create feature test exercising the new formatter (features/config_formatters.feature or new feature file)

Add a new coverage metric or validation rule

1. Add calculation logic to SimpleCov::CoverageStatistics for metrics (lib/simplecov/coverage_statistics.rb)
2. Add validation logic to SimpleCov::CoverageViolations for thresholds (lib/simplecov/coverage_violations.rb)
3. Expose configuration option in SimpleCov::Configuration (lib/simplecov/configuration.rb)
4. Create feature test validating the metric is enforced (features/minimum_coverage*.feature or new feature file)

Improve HTML report display

1. Update HTML template or add new asset file in html_frontend/src (html_frontend/src/app.ts or html_frontend/assets/stylesheets/*.css)
2. Modify HTML formatter to pass new data to template (lib/simplecov-html.rb)
3. Compile assets via rake assets:compile (html_frontend/package.json build script)
4. Test report rendering with pagination or HTML feature tests (features/pagination.feature or features/step_definitions/html_steps.rb)

• Ruby Coverage module (stdlib) — Only standard way to collect line and branch coverage in Ruby; avoids external C extension dependencies
• JSON for merged results (.resultset.json) — Language-agnostic, human-readable format for persisting coverage across parallel processes and merging runs
• HTML5 + TypeScript frontend — Enables interactive, searchable coverage reports without server-side dependencies; esbuild keeps assets minimal
• Cucumber BDD tests — Documents user-facing features in plain language; catches integration regressions with real test runners (RSpec, Minitest, Cucumber)
• RuboCop + YARD docs — Enforces Ruby style consistency and generates API docs for gem users

• Merging coverage across parallel processes via filesystem (.resultset.json files)

  • Why: Avoids IPC/network complexity; works with any parallel runner (parallel_tests, CI matrix jobs, custom scripts)
  • Consequence: Requires poll-wait logic and merge timeout; risk of race conditions if cleanup timing is poor

• HTML report as static file (no embedded server)

  • Why: Zero runtime overhead; works in sandboxed CI/CD environments; no port conflicts
  • Consequence: No real-time updating; users must manually refresh; navigation is client-side only

• Filters and groups applied at result-time, not collection-time

  • Why: Allows retroactive filtering without re-running tests; easier configuration
  • Consequence: Includes irrelevant code in Coverage.result() data structure; slightly slower final processing

• Single responsibility: coverage tracking only (no assertions in config)

  • Why: SimpleCov focuses on collection; validation (minimum_coverage) is separate; avoids bloat
  • Consequence: Users need separate CI/CD step to assert thresholds; slightly more boilerplate

• Does not instrument code or mock standard library; relies entirely on Ruby's built-in Coverage

Coverage merging requires understanding SimpleCov's cache directory behavior (inferred from 'config_deactivate_merging.feature'); parallel test runs need subprocess tracking enabled ('config_enable_for_subprocesses.feature'). Ruby version compatibility critical—Coverage API changed across major Ruby versions. The 'nocov' token (nocov_token config) has specific syntax that can silently fail if misformatted. Branch coverage requires Ruby 2.5+ but feature detection is implicit, not explicit in defaults. TypeScript compilation for assets requires Node.js in development (not just Ruby).

• Ruby Coverage API (stdlib) — SimpleCov's entire foundation; you must understand what Coverage.start!, Coverage.result, and line/branch coverage modes do to debug coverage collection issues
• Coverage Merging & De-duplication — Core feature of SimpleCov that distinguishes it from basic Coverage API usage; merging handles overlapping coverage from RSpec + Cucumber + parallel test runs, implemented in result.rb and tested extensively in features/merging_*.feature
• Formatter Plugin Architecture — SimpleCov uses a pluggable formatter system (lib/simplecov/formatter.rb) where users can inject custom processors; understanding the #format(result) contract is essential for extending output
• Configuration DSL (Fluent Interface) — SimpleCov's user-facing API is a fluent/chainable configuration block; understanding blocks, yield, and method chaining in Ruby is critical for reading and debugging user config in features/config_*.feature
• Result Filtering & Tracking — SimpleCov allows filtering coverage by file patterns, line ranges, and groups; filtering logic in result.rb determines what shows in reports, tested in features/config_tracked_files*.feature
• Branch vs. Line Coverage — SimpleCov supports both line and branch coverage modes (Ruby 2.5+); branch coverage requires understanding if/else/case/loop paths, configured in features/branch_coverage.feature and critical for teams aiming for comprehensive metrics
• Process-level Merge & Subprocess Isolation — SimpleCov handles coverage from parallel test processes that may run in subprocesses; the merge timeout, cache directory, and subprocess tracking (config_enable_for_subprocesses.feature) prevent race conditions and data loss in parallel runs

• simplecov-ruby/simplecov-html — Official HTML formatter gem; separate dependency that SimpleCov auto-installs and delegates all HTML report generation to
• colszowka/simplecov-console — Community formatter for terminal/console output; example of SimpleCov's formatter plugin pattern used by teams preferring CI log visibility
• rspec/rspec — Primary test framework integrated with SimpleCov; RSpec adapter is bundled in Gemfile and most SimpleCov examples use RSpec
• cucumber/cucumber-ruby — Gherkin test framework; SimpleCov merges RSpec + Cucumber coverage automatically, and integration tested via features/cucumber_basic.feature and merging_test_unit_and_rspec.feature
• grosser/parallel_tests — Parallel test runner; SimpleCov's merge logic and subprocess tracking (config_enable_for_subprocesses.feature) exist specifically to handle parallel_tests' split coverage data

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add TypeScript type definitions and strengthen typecheck workflow

The repo has a TypeScript dependency and typecheck workflow, but no visible tsconfig.json or type definition files. The package.json indicates a 'typecheck' script exists, but there's no evidence of .ts files or a proper TypeScript setup. Adding proper type definitions would improve the developer experience and catch errors early, especially important for a gem that's widely used. This is particularly valuable since the repo already invests in the typecheck workflow.

• [ ] Create tsconfig.json with appropriate compiler options for the project structure
• [ ] Add TypeScript definitions for key modules in lib/ directory (if applicable to the Ruby gem's JS components)
• [ ] Verify the existing .github/workflows/typecheck.yml workflow references valid TypeScript files
• [ ] Add type checking to the CI pipeline if not already enforced

Add comprehensive feature test for JSON formatter output schema validation

The repo has a features/config_json_formatter.feature file and features/old_version_json.feature for backwards compatibility testing. However, there's no feature test validating the JSON schema structure itself (keys, types, required fields). This would catch regressions when the JSON output format changes and ensure formatters produce valid output. The old_version_json.feature suggests format changes are expected, making schema validation critical.

• [ ] Review features/config_json_formatter.feature and features/old_version_json.feature to understand current test scope
• [ ] Create features/json_formatter_schema_validation.feature with Gherkin scenarios validating JSON structure
• [ ] Add step definitions in features/step_definitions/ to parse JSON output and validate against expected schema
• [ ] Include tests for required fields like coverage_percent, files array, and file-level metrics

Add integration test for simplecov with Rails 8+ and async test execution

The repo has features/rspec_rails.feature but no explicit coverage for modern Rails async test features (async/await test patterns, Rails 8+ parallel execution modes). The features/parallel_tests.feature exists but targets the parallel_tests gem specifically. As Rails 8+ introduces native async testing, adding a feature test would ensure SimpleCov works correctly with the latest Rails testing paradigms and catch integration issues early.

• [ ] Review features/rspec_rails.feature to understand current Rails integration test structure
• [ ] Create features/rspec_rails_async.feature for Rails 8+ async test execution scenarios
• [ ] Add corresponding step definitions in features/step_definitions/simplecov_steps.rb or create features/step_definitions/rails_async_steps.rb
• [ ] Test coverage merging behavior when tests execute asynchronously across multiple processes

• Add missing type definitions or TypeScript stubs for core SimpleCov classes in lib/simplecov/ (currently only assets use TypeScript per package.json); this enables better IDE support and identifies API gaps.
• Expand features/config_*.feature test coverage: add Gherkin scenarios for edge cases in minimum_coverage_by_file.feature (e.g., excluding files from minimum check, handling zero-coverage files) and maximum_coverage_drop.feature (fractional percentage thresholds).
• Create doc/integration-guides/ markdown files for popular CI/CD platforms (GitHub Actions, GitLab CI, CircleCI) showing SimpleCov config patterns for parallel test merging, parallel_tests gem, and timeout handling (features/config_merge_timeout.feature exists but no guide).

The codebase demonstrates a reasonably secure posture with some areas for improvement. The project uses standard tooling and has infrastructure for dependency management (Dependabot). However, there are moderate concerns around frontend dependencies (TypeScript 6.x is very new, highlight.js has historical XSS vulnerabilities) and potential XSS risks in the HTML frontend that merit code review. The presence of GitHub Actions workflows for linting and type-checking suggests good development practices. No hardcoded secrets were detected in visible file paths. The main recommendations are to: (1) audit the HTML frontend code for proper input sanitization and XSS prevention, (2) implement CSP headers, (3) ensure regular dependency updates, and (4) consider stabilizing TypeScript to a more mature version.

• Medium · Outdated TypeScript Dependency — html_frontend/package.json. The package.json specifies TypeScript ^6.0.3, which is a major version that may contain breaking changes and potential security issues. TypeScript 6.x is very recent and may not have been thoroughly vetted for security vulnerabilities. Fix: Consider pinning to a stable, well-tested version of TypeScript (e.g., ^5.x) or regularly audit for security updates. Monitor the TypeScript release notes for any security advisories.
• Medium · Highlight.js Dependency Security — html_frontend/package.json. The highlight.js library version ^11.11.1 is used for syntax highlighting. While this is a legitimate use case, highlight.js has historically had XSS vulnerabilities. The caret version allows minor updates that could introduce security regressions. Fix: Regularly audit highlight.js for CVEs. Consider implementing Content Security Policy (CSP) headers in the HTML frontend to mitigate XSS risks. Test any updates in a staging environment before production deployment.
• Low · Potential XSS Risk in HTML Frontend — html_frontend/src/. The presence of html_frontend/src/app.ts and index.html suggests dynamic HTML generation. Without reviewing the actual code, there's a potential risk of XSS if user input or coverage data is rendered without proper sanitization. Fix: Ensure all user input and dynamically generated content is properly escaped/sanitized. Use framework-provided escaping mechanisms. Implement Content Security Policy headers. Avoid using innerHTML with untrusted data.
• Low · Missing Dependency Lock File Management — html_frontend/. While package-lock.json or bun.lock should exist, the security posture depends on regular updates and vulnerability scanning of npm dependencies. Fix: Ensure bun.lock or package-lock.json is committed to version control. Use automated dependency scanning tools (e.g., npm audit, Dependabot) and keep dependencies updated. The .github/dependabot.yml file suggests this is being done, which is good.
• Low · Build Process Security — html_frontend/package.json. The esbuild tool (^0.28.0) is used for compilation. Build tools can be vectors for supply chain attacks if compromised or if malicious plugins are used. Fix: Verify the integrity of build dependencies. Use npm package integrity checks. Review esbuild configuration for any unsafe options. Consider using SRI (Subresource Integrity) for any externally loaded resources.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.