coverband 6.2.2 → 7.0.0.rc.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 20188ba8fca24027b2a7bd367ac88586b7dace04a6eadfd9714bdf509849683e
-  data.tar.gz: c2db00de6ffaa32256d083c7d51290a5936f5e2ee46c774eed901f91fa0ba545
+  metadata.gz: 122ec261f93431af71ca87c0113241a9197af2daa07c3d32013b98d893cd3a78
+  data.tar.gz: 785fa634bdba056657cb2b0e358f387decb4aa020faee0f50580dedd929ddcaa
 SHA512:
-  metadata.gz: 22b5b1281136a3ed3172383d84526f1659568e6b204cc38b636d929c76b8ec84c9b70d20e61a54484cf97d8604e268de9da87cc596bbff2cbb81752c1078ca8b
-  data.tar.gz: aa55b358d2a3a196fd5de29f850ad41a877274649ccf377395a114c6e940bc926424fccbe6a3e7642225eaa81432f73094443b5874c8e79ac75cccb39a6c3422
+  metadata.gz: 990b9e30e696866dd1e68e8c26b394608c3697f8564ea0ff2683592d1b02fabaae5a0dcc0aa4e3c7a12e73cef259aa2f441fd154a910cb7694c0d10acfb9dab7
+  data.tar.gz: 43c6e3982076da3771c7a961a9ac7c409c8576731d8e76b4a943a67323ff4e3391f9b96de89ba5050ee1c2868a436b25c9a386265d643bf82b053c6b65953f20

data/.github/workflows/diagram.yml

@@ -6,7 +6,7 @@ on:
       - main
 jobs:
   get_data:
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-24.04
     steps:
       - name: Checkout code
         uses: actions/checkout@master
@@ -14,4 +14,4 @@ jobs:
         uses: githubocto/repo-visualizer@main
         with:
           excluded_paths: "ignore,.github"
-          branch: diagram
+          branch: diagram

data/.github/workflows/main.yml

@@ -13,8 +13,8 @@ jobs:
       fail-fast: false
       matrix:
         # need to figure out how to use redis on macos github actions
-        # os: [ubuntu, macos]
-        os: [ubuntu]
+        # os: [ubuntu-24.04, macos-15]
+        os: [ubuntu-24.04]
         # remove until I sort out CI issues for truffle
         # truffleruby,
         # truffleruby-head,
@@ -25,9 +25,11 @@ jobs:
         redis-version: [4, 5, 6, 7]
         exclude:
           # Rails 8 requires ruby 3.2+.
-          - gemfile: 'rails_8.0'
+          - gemfile: 'Gemfile.rails8.0'
             ruby: '3.1'
-    runs-on: ${{ matrix.os }}-latest
+    runs-on: ${{ matrix.os }}
+    env:
+      BUNDLE_GEMFILE: ${{ matrix.gemfile }}
     services:
       redis:
         image: redis:${{ matrix.redis-version }}
@@ -38,6 +40,15 @@ jobs:
           --health-interval 10s
           --health-timeout 5s
           --health-retries 5
+      memcached:
+        image: memcached:1.6
+        ports:
+          - 11211:11211
+        options: >-
+          --health-cmd "timeout 2 bash -c '</dev/tcp/127.0.0.1/11211'"
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
     steps:
       - uses: actions/checkout@v7
       - uses: ruby/setup-ruby@v1
@@ -45,9 +56,26 @@ jobs:
           ruby-version: ${{ matrix.ruby }}
           bundler-cache: true # runs 'bundle install' and caches installed gems automatically
       - run: bundle exec rake test:all
+        env:
+          # the memcached adapter has an ENV gate so local runs need no service,
+          # which also meant CI never exercised it
+          COVERBAND_MEMCACHED: "true"
       - run: "RUBYOPT='--enable=frozen-string-literal --debug=frozen-string-literal' bundle exec rake"
+        env:
+          COVERBAND_MEMCACHED: "true"
+      # Solid Cache needs Rails 7.2+, and its engine changes process wide state,
+      # so it runs on its own, only where it is available.
+      #
+      # Its gems sit in an optional bundler group, which bundler-cache does not
+      # install, so the group is installed here rather than assumed present.
+      - name: Solid Cache adapter tests
+        if: matrix.gemfile == 'Gemfile.rails8.0'
+        run: |
+          bundle config set --local with solid_cache
+          bundle install --jobs 4
+          bundle exec rake test:solid_cache
   starndardrb:
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-24.04
     steps:
       - uses: actions/checkout@v7
       - uses: ruby/setup-ruby@v1
@@ -56,10 +84,10 @@ jobs:
           bundler-cache: true # runs 'bundle install' and caches installed gems automatically
       - run: bundle exec standardrb --format github
   javascript:
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-24.04
     steps:
       - uses: actions/checkout@v7
-      - uses: actions/setup-node@v4
+      - uses: actions/setup-node@v7
         with:
           node-version: "20"
       - run: node --test test/javascript/*.test.mjs

data/Gemfile

@@ -11,3 +11,18 @@ gem "webrick"
 
 # Required for Ruby 3.4+ (extracted from stdlib)
 gem "cgi"
+
+# ActiveSupport 8.1's MemCacheStore passes positional options to ConnectionPool,
+# which connection_pool 3.x turned into keyword arguments. Pinned so the
+# memcached backed cache adapter tests can actually run.
+gem "connection_pool", "~> 2.5"
+
+# Solid Cache is a central target for the ActiveSupport::Cache adapter: it is
+# how Coverband reaches Postgres, MySQL, and SQLite. Needs Rails 7.2+.
+#
+# Kept out of the default group on purpose: the dummy Rails apps require every
+# default gem, and Solid Cache's engine expects an ActiveJob they do not load.
+group :solid_cache, optional: true do
+  gem "solid_cache"
+  gem "sqlite3"
+end

data/Gemfile.rails7.0

@@ -9,5 +9,16 @@ gem "haml"
 gem "slim"
 gem "webrick"
 
+# ActiveSupport's MemCacheStore passes positional options to ConnectionPool,
+# which connection_pool 3.x turned into keyword arguments.
+gem "connection_pool", "~> 2.5"
+
+# Rack 2 requires ostruct, which Ruby 4 no longer ships as a default gem.
+gem "ostruct"
+
 # Required for Ruby 3.4+ (extracted from stdlib)
 gem "cgi"
+
+# railties 7.0 requires tsort without declaring it, and Ruby 4.1 no longer
+# ships it as a default gem.
+gem "tsort"

data/Gemfile.rails7.1

@@ -9,5 +9,9 @@ gem "haml"
 gem "slim"
 gem "webrick"
 
+# ActiveSupport's MemCacheStore passes positional options to ConnectionPool,
+# which connection_pool 3.x turned into keyword arguments.
+gem "connection_pool", "~> 2.5"
+
 # Required for Ruby 3.4+ (extracted from stdlib)
-gem "cgi"
+gem "cgi"

data/Gemfile.rails7.2

@@ -9,5 +9,9 @@ gem "haml"
 gem "slim"
 gem "webrick"
 
+# ActiveSupport's MemCacheStore passes positional options to ConnectionPool,
+# which connection_pool 3.x turned into keyword arguments.
+gem "connection_pool", "~> 2.5"
+
 # Required for Ruby 3.4+ (extracted from stdlib)
 gem "cgi"

data/Gemfile.rails8.0

@@ -9,5 +9,19 @@ gem "haml"
 gem "slim"
 gem "webrick"
 
+# ActiveSupport's MemCacheStore passes positional options to ConnectionPool,
+# which connection_pool 3.x turned into keyword arguments.
+gem "connection_pool", "~> 2.5"
+
 # Required for Ruby 3.4+ (extracted from stdlib)
 gem "cgi"
+
+# Solid Cache is a central target for the ActiveSupport::Cache adapter: it is
+# how Coverband reaches Postgres, MySQL, and SQLite. Needs Rails 7.2+.
+#
+# Kept out of the default group on purpose: the dummy Rails apps require every
+# default gem, and Solid Cache's engine expects an ActiveJob they do not load.
+group :solid_cache, optional: true do
+  gem "solid_cache"
+  gem "sqlite3"
+end

data/README.md

@@ -3,7 +3,6 @@
 # Coverband
 
 [![GithubCI](https://github.com/danmayer/coverband/workflows/CI/badge.svg)](https://github.com/danmayer/coverband/actions)
-[![Coverage Status](https://coveralls.io/repos/github/danmayer/coverband/badge.svg?branch=main)](https://coveralls.io/github/danmayer/coverband?branch=main)
 [![Maintainability](https://api.codeclimate.com/v1/badges/1e6682f9540d75f26da7/maintainability)](https://codeclimate.com/github/danmayer/coverband/maintainability)
 [![Discord Shield](https://img.shields.io/discord/609509533999562753)](https://discord.gg/KAH38EV)
 
@@ -69,12 +68,15 @@ The `rediss://` scheme works with:
 
 ## Gem Installation
 
-Add this line to your application's `Gemfile`, remember to `bundle install` after updating:
+Add these lines to your application's `Gemfile`, remember to `bundle install` after updating:
 
-```bash
+```ruby
 gem 'coverband'
+gem 'redis' # the default store
 ```
 
+Redis is the default store and needs no configuration beyond a reachable Redis. Since Coverband 7.0 the `redis` gem is no longer installed for you, so add it yourself as above. If you would rather keep coverage somewhere else (Solid Cache, memcached, files), leave out `redis` and set `config.store`, see [ActiveSupport::Cache Store](#activesupportcache-store). Without the `redis` gem and without a configured store, Coverband logs a warning at boot and records nothing. Upgrading from 6.x? See [Upgrading to 7.0](#upgrading-to-70).
+
 ### No custom code or middleware required
 
 With older versions of Coverband, projects would report to redis using rack or sidekiq middleware. After Coverband 4.0, this should no longer be required and could cause performance issues. Reporting to redis is now automatically done within a background thread with no custom code needed.
@@ -97,6 +99,46 @@ use Coverband::BackgroundMiddleware
 run ActionController::Dispatcher.new
 ```
 
+## Upgrading to 7.0
+
+7.0 is a major release with breaking changes. Most apps only need the first two steps. The full list is in the [changelog](https://github.com/danmayer/coverband/blob/main/changes.md).
+
+1. **Add the `redis` gem if you use Redis.** Coverband no longer installs it for you. Redis is still the default store and still needs no other configuration once the gem is in your Gemfile:
+
+   ```ruby
+   gem 'coverband'
+   gem 'redis'
+   ```
+
+   Without it, and without a configured `config.store`, Coverband logs a warning at boot and records nothing.
+
+2. **Coverage starts fresh.** The storage format changed, so data recorded by 6.x is ignored rather than migrated. Once you are happy with the new data, delete the old keys with `rake coverband:clear_legacy` (Redis only).
+
+3. **Delete removed settings from `config/coverband.rb`.** These now do nothing. Assigning one logs a warning naming the setting, but the app still boots:
+
+   | Setting | What to do |
+   | --- | --- |
+   | `reporter` | Delete it. It has had no effect since Coverband 5.0. |
+   | `api_key`, `service_url`, `coverband_timeout`, `service_dev_mode`, `service_test_mode`, `process_type` | Delete them, see the coverband.io step below. |
+   | `s3_region`, `s3_bucket`, `s3_access_key_id`, `s3_secret_access_key`, `track_gems`, `gem_details`, `simulate_oneshot_lines_coverage` | Delete them. They were already no-ops. |
+
+4. **coverband.io users: configure a store.** coverband.io is no longer maintained, so reporting to it (`WebServiceStore`) has been removed, along with `config/coverband_service.rb` and the `COVERBAND_API_KEY`, `COVERBAND_URL`, `COVERBAND_ENABLE_DEV_MODE`, `COVERBAND_ENABLE_TEST_MODE`, and `PROCESS_TYPE` environment variables. Move any settings from `config/coverband_service.rb` into `config/coverband.rb` and use Redis (step 1) or an [ActiveSupport::Cache store](#activesupportcache-store).
+
+5. **`MemcachedStore` users: switch to `ActiveSupportCacheStore`.** `MemcachedStore` has been removed. The replacement takes the same cache and adds tracker support:
+
+   ```ruby
+   # before
+   config.store = Coverband::Adapters::MemcachedStore.new(cache, memcached_namespace: "myapp")
+   # after
+   config.store = Coverband::Adapters::ActiveSupportCacheStore.new(cache, cache_namespace: "myapp")
+   ```
+
+6. **Custom code against Coverband internals.** Only relevant if you wrote a tracker or call adapters directly:
+   - In a custom tracker, use `storage` instead of `redis_store`.
+   - Instead of `store.raw_store`, use `store.cleanup` (`clear_legacy!`, `clear_orphans!`), which returns `nil` for stores that cannot enumerate keys.
+   - Replace calls to the misspelled `Coverband::Utils::Results#runtime_relavent_lines` with `#runtime_relevant_lines`; the old spelling was removed in 7.0.
+   - `Coverband::Utils::SourceFile` and `Coverband::Utils::Result` take stored report records (`{"data" => [...]}`) rather than bare line arrays.
+
 ## Coverband Web UI
 
 ![image](https://raw.github.com/danmayer/coverband/main/docs/coverband_web_ui.png)
@@ -129,15 +171,20 @@ run ActionController::Dispatcher.new
 
 The columns in the web UI are as follows:
 
-- **% covered** - Percentage of total relevant lines covered
-- **% runtime** - Percentage of the runtime lines covered where runtime lines are lines that are hit after the application has been eagerly loaded
+- **% covered** - Percentage of relevant lines covered, during either eager loading or runtime
+- **% runtime** - Percentage of the runtime relevant lines that were hit at runtime. Runtime relevant lines are the relevant lines that were *not* hit while the application eager loaded, so this is the share of the code that only real usage can exercise (method bodies, branches, etc.) which real usage actually exercised
 - **Lines** - Total lines in the file including lines unreachable or uncover-able. An unreachable line would be an empty line with no code, comments, or `end` statements.
 - **Relevant lines** - Lines that are coverable, i.e. not empty
-- **Lines runtime** - Total lines minus uncoverable lines minus the lines that are only hit during eager loading of application
+- **Lines covered** - Relevant lines hit during either eager loading or runtime
+- **Lines runtime** - Relevant lines hit at least once at runtime
 - **Lines missed** - Relevant lines not covered
 - **Avg hits/line** - Total of coverage to the file divided by relevant lines.
 
-When viewing an individual file, a line of code such as a class or method definition may appear green because it is eager loaded by the application, but still not be hit at all in runtime by actual users.  
+The individual file view also lists the file's **runtime relevant lines**, the denominator of **% runtime**. A file only reports 100% runtime when every one of its runtime relevant lines was hit at runtime. If a file was never eager loaded (the default in development), every relevant line is runtime relevant, so **% runtime** matches **% covered**.
+
+**Lines runtime** can include load time lines such as class and method definitions. Those lines are hit at runtime when a process loads the file lazily after Coverband switched to runtime coverage, e.g. a console, runner, or job process that does not eager load. Such lines still count as eager loaded for **% runtime** as long as any process loaded them during eager loading.
+
+When viewing an individual file, a line of code such as a class or method definition may appear green because it is eager loaded by the application, but still not be hit at all in runtime by actual users. Each line's badge shows its `load` (eager loading) and `runtime` hit counts separately.  
 
 ![example of a file with lines not hit at runtime](https://user-images.githubusercontent.com/96786/63541229-aa98a580-c4eb-11e9-8eb8-c004fe1369db.png)
 #### Coverage first seen and Last activity recorded
@@ -233,7 +280,7 @@ Take Coverband for a spin on the live Heroku deployed [Coverband Demo](https://c
 If you need to configure Coverband, this can be done by creating a `config/coverband.rb` file relative to your project root.
 
 - See [lib/coverband/configuration.rb](https://github.com/danmayer/coverband/blob/main/lib/coverband/configuration.rb) for all options
-- By default Coverband will try to store data to Redis \* Redis endpoint is looked for in this order: `ENV['COVERBAND_REDIS_URL']`, `ENV['REDIS_URL']`, or `localhost`
+- By default Coverband will try to store data to Redis (when the `redis` gem is installed) \* Redis endpoint is looked for in this order: `ENV['COVERBAND_REDIS_URL']`, `ENV['REDIS_URL']`, or `localhost`
 
 Below is an example config file for a Rails 5 app:
 
@@ -358,6 +405,61 @@ For each tracked key, the Query Burst Tracker reports:
 
 Tip: use this tracker in production-like traffic, where query patterns are most realistic.
 
+### Writing a Custom Tracker
+
+Trackers can be shipped by an application or a separate gem without changing Coverband. A tracker subclasses `Coverband::Collectors::AbstractTracker`, registers itself once when its file is required, and is initialized at Rails boot when its enablement block returns true.
+
+```ruby
+# lib/my_app/coverband/feature_flag_tracker.rb
+class FeatureFlagTracker < Coverband::Collectors::AbstractTracker
+  # required: the path this tracker reports on inside the Coverband web report,
+  # and the label for its tab
+  REPORT_ROUTE = "feature_flag_tracker"
+  TITLE = "Feature Flags"
+
+  def railtie!
+    tracker = self
+    ActiveSupport::Notifications.subscribe("feature_flag.my_app") do |_name, _start, _finish, _id, payload|
+      tracker.track_key(payload.fetch(:key))
+    end
+  end
+
+  private
+
+  def concrete_target
+    MyApp::FeatureFlags.all.map(&:key)
+  end
+end
+
+Coverband::Configuration.add_tracker_flag(:track_feature_flags, default: false)
+Coverband::Collectors::TrackerRegistry.register(
+  :feature_flag_tracker,
+  tracker_class: FeatureFlagTracker,
+  enabled: ->(config) { config.track_feature_flags }
+)
+```
+
+Require the tracker before enabling it in `config/coverband.rb`:
+
+```ruby
+require "my_app/coverband/feature_flag_tracker"
+
+Coverband.configure do |config|
+  config.track_feature_flags = true
+end
+```
+
+Every tracker must declare its own `REPORT_ROUTE`. `AbstractTracker`'s default of `"/"` matches every path in the web report, so a tracker that inherits it would answer all of Coverband's own report routes. Registering such a tracker raises `ArgumentError` rather than letting it take over the UI.
+
+`tracker_class` may also be a callable that returns a tracker instance when initialization needs to choose an implementation. Registration and enablement are evaluated at boot, not on every request. Duplicate tracker names raise `ArgumentError` so load-order mistakes fail early. Coverband's Query Burst Tracker is a bundled example of the same registration pattern.
+
+Trackers registered this way have no dedicated `Coverband.configuration` accessor, so reach them by their registered name:
+
+```ruby
+Coverband.configuration.tracker_for(:feature_flag_tracker)
+Coverband.track_key(:feature_flag_tracker, "flags.new_checkout")
+```
+
 ### Hiding settings
 
 Coverband provides a view of all of its current settings. Sometimes you might want to hide this view,
@@ -376,6 +478,14 @@ The web report includes a client-side "dead-code session" toolbar to help drive
 
 Session state lives in your browser's localStorage: "Reset session" clears the hidden set; "Start over" (in the modal) clears the marked list.
 
+### Dark mode
+
+The web report follows your operating system's appearance setting through the CSS `prefers-color-scheme` media query. There is nothing to configure and no toggle in the UI: if your desktop is in dark mode, the report is dark, and it switches back when your desktop does. Printing always uses the light theme.
+
+The coverage row colors (covered / missed / never / skipped) are chosen for contrast on the dark surface rather than darkened mechanically, so the states stay as easy to tell apart as in the light theme.
+
+If you restyle the report, every color in `public/application.css` resolves through a custom property defined on `:root`, and the dark theme is a single `@media (prefers-color-scheme: dark)` block that redefines those properties. Overriding a property is enough to change both themes from one place.
+
 ### Fixing Coverage Only Shows Loading Hits
 
 If all your coverage is being counted as loading or eager_loading coverage, and nothing is showing as runtime Coverage the initialization hook failed for some reason. The most likely reason for this issue is manually calling `eager_load!` on some Plugin/Gem. If you or a plugin is altering the Rails initialization process, you can manually flip Coverband to runtime coverage by calling these two lines, in an `after_initialize` block, in `application.rb`.
@@ -441,6 +551,55 @@ Coverband on very high volume sites with many server processes reporting can hav
 
 See more discussion [here](https://github.com/danmayer/coverband/issues/384).
 
+### ActiveSupport::Cache Store
+
+Coverband can store coverage in any `ActiveSupport::Cache::Store`, which covers
+Redis, Memcached, files, and — through [Solid Cache](https://github.com/rails/solid_cache) —
+Postgres, MySQL, and SQLite.
+
+```ruby
+# Rails.cache does not exist yet when config/coverband.rb loads, so pass a block
+config.store = Coverband::Adapters::ActiveSupportCacheStore.new { Rails.cache }
+
+# or hand it a store directly
+config.store = Coverband::Adapters::ActiveSupportCacheStore.new(
+  ActiveSupport::Cache::MemCacheStore.new("localhost:11211")
+)
+```
+
+The block form is the one to use with Solid Cache: its models come from a Rails
+engine that has not loaded when `config/coverband.rb` runs, so building a
+`SolidCache::Store` there raises `uninitialized constant
+SolidCache::Store::Entries::Entry`.
+
+Coverband starts from `before_configuration`, which is earlier than Rails
+assigns `Rails.cache`, so the first reporting cycle can run before the block can
+resolve. That cycle's coverage is held and written once the cache appears; it is
+not lost, and it does not raise into the booting app.
+
+This adapter supports the view, route, translation, and query burst trackers.
+It replaces `MemcachedStore`, which was removed in 7.0 (see
+[Upgrading to 7.0](#upgrading-to-70)).
+
+Things to know before pointing it at a cache:
+
+- **A cache may evict what Coverband writes.** Use a store that will not expire
+  the data: a dedicated Solid Cache database with `max_age: nil` plus a size
+  limit, or a Redis instance with no eviction policy. Coverband detects the loss
+  and reports it in the web UI when it can, but it cannot prevent it.
+- **Memcached's 1MB value limit applies to every document**, trackers included.
+  A large translation or view tracker can exceed it, in which case the write is
+  refused and Coverband logs what could not be stored. Raise the slab limit
+  (`-I`) or use Redis/Solid Cache for large apps.
+- **`ActiveSupport::Cache::MemoryStore` is per process**, so it is only useful
+  for development and tests.
+- **Solid Cache** writes go through ActiveRecord, so size your connection pool
+  for one extra connection per process, and prefer a separate cache database so
+  Coverband's writes do not evict your application's own cached data.
+- For very large multi-process deployments `Coverband::Adapters::HashRedisStore`
+  is still the best option: it avoids write conflicts entirely rather than
+  repairing them.
+
 ### Clear Coverage
 
 Now that Coverband uses MD5 hashes there should be no reason to manually clear coverage unless one is testing, changing versions, or possibly debugging Coverband itself.
@@ -452,6 +611,28 @@ This will clear both the coverage and trackers data. It can also be done through
 To clear only coverage data, run `rake coverband:clear_coverage`.
 To clear only trackers data, run `rake coverband:clear_tracker`.
 
+Redis-backed stores also support two maintenance tasks:
+
+- `rake coverband:clear_legacy` removes Coverband-owned keys from storage
+  formats retired by the 7.0 upgrade.
+- `rake coverband:clear_orphans` removes old generation documents that no
+  pointer references, after rechecking that each candidate is not live or too
+  young to delete safely.
+
+In Coverband 7.0, adapters no longer expose their backend through `raw_store`.
+Code that needs these supported maintenance operations can request the narrow
+capability instead:
+
+```ruby
+cleanup = Coverband.configuration.store.cleanup
+cleanup&.clear_legacy!
+cleanup&.clear_orphans!
+```
+
+`RedisStore` and `HashRedisStore` provide this capability. Adapters that cannot
+enumerate their keys return `nil`; clear the backing cache or rely on its expiry
+policy for those stores.
+
 ### Adding Rake Tasks outside of Rails
 
 Rails apps should automatically include the tasks via the Railtie.
@@ -550,6 +731,28 @@ The MCP server provides the following tools:
 | `get_view_tracker_data` | Get view/template usage data |
 | `get_route_tracker_data` | Get route usage statistics |
 | `get_translation_tracker_data` | Get translation key usage data |
+| `get_storage_health` | Get observed coverage and tracker storage protocol state |
+
+#### Storage health
+
+`Coverband.storage_health` returns normalized diagnostics for coverage and every initialized
+tracker. The normal JSON report also includes this value as its top-level `storage_health`
+field, and MCP exposes the same representation through `get_storage_health`:
+
+```ruby
+Coverband.storage_health
+# => {
+#   coverage: {status: "ok", data_loss: nil, unwritten: nil},
+#   trackers: {view_tracker: {status: "stalled", data_loss: nil,
+#     unwritten: {deltas: 3, since: "2026-08-19T12:01:00Z"}}}
+# }
+```
+
+Statuses are `ok`, `stalled`, `data_loss`, or `unsupported`; `data_loss` takes precedence
+when both loss and unwritten work are present. These diagnostics describe state Coverband's
+storage protocol has already observed. They are not an active backend availability or
+connectivity probe. SimpleCov-compatible JSON generated with `for_merged_report` does not
+include this metadata.
 
 #### Running the MCP Server
 
@@ -673,7 +876,7 @@ Outputs:
 # Prerequisites
 
 - Ruby 3.1+
-- Coverband currently requires Redis for production usage
+- A production store: Redis by default (add the `redis` gem), or any `ActiveSupport::Cache` store such as Solid Cache or memcached
 
 ### Ruby and Rails Version Support
 
@@ -721,13 +924,16 @@ If you submit a change please make sure the tests and benchmarks are passing.
 - **total fail** on front end code, for line for line coverage, because of the precompiled template step basically coverage doesn't work well for `erb`, `slim`, and the like.
   - related it will try to report something, but the line numbers reported for `ERB` files are often off and aren't considered useful. I recommend filtering out .erb using the `config.ignore` option. The default configuration excludes these files
   - **NOTE:** We now have file level coverage for view files, but don't support line level detail
-- **Coverage does NOT work when used alongside Scout APM Auto Instrumentation**
-  - In an environment that uses Scout's `AUTO_INSTRUMENT=true` (usually production or staging) it stops reporting any coverage, it will show one or two files that have been loaded at the start but everything else will show up as having 0% coverage
+- **Scout APM Auto Instrumentation** — fixed in Ruby 3.4.10 / 4.0.4, broken on earlier Rubies
+  - **Symptom:** in an environment that uses Scout's auto instruments (usually production or staging) Coverband stops reporting coverage. You will see one or two files loaded at the start, and everything else shows up as 0% / never loaded. This is dangerous: live code, particularly your controllers, gets reported as dead code.
+  - **Cause:** this is a Ruby bug, not a bug in Coverband or Scout. Scout's auto instrumentation installs a `RubyVM::InstructionSequence.load_iseq` hook and loads your files through `RubyVM::InstructionSequence.compile` / `.compile_file`. Until recently those methods did not register a file with the `Coverage` module the way a normal `require` does, so the file was never measured and never even appeared in `Coverage.result`. Note that this affected *every* file loaded while the hook was installed, not just the controllers Scout rewrites, which is why coverage appears to vanish entirely.
+  - **Fix:** upgrade to **Ruby >= 3.4.10 or >= 4.0.4**, which include the fix for [Ruby Bug #22018](https://bugs.ruby-lang.org/issues/22018). Coverband and Scout auto instruments then work together with no configuration changes and no minimum version of either gem. Both `lines` and `oneshot_lines` collection modes are unaffected.
+  - **Workaround for Ruby <= 3.3:** the fix was not backported to Ruby 3.1, 3.2, or 3.3, so on those versions you must disable auto instruments to collect coverage — set `auto_instruments: false` in `scout_apm.yml` or `SCOUT_AUTO_INSTRUMENTS=false` in the environment.
   - Bug tracked here: https://github.com/scoutapp/scout_apm_ruby/issues/343
 - **Coverband, [Elastic APM](https://github.com/elastic/apm-agent-ruby) and resque**
   - In an environment that uses the Elastic APM ruby agent, resque jobs will fail with `Transactions may not be nested. Already inside #<ElasticAPM::Transaction>` if the `elastic-apm` gem is loaded _before_ the `coverband` gem
   - Put `coverage` ahead of `elastic-apm` in your Gemfile
-- **Bootsnap**, The methods used by [bootsnap do not support having coverage enabled](https://github.com/Shopify/bootsnap/blob/main/lib/bootsnap/compile_cache/iseq.rb#L87), so you can either have Coverband or bootsnap, but not both.  
+- **Bootsnap**, you can run bootsnap alongside Coverband, but you lose part of the boot time speedup. [Bootsnap detects that coverage is enabled](https://github.com/Shopify/bootsnap/blob/main/lib/bootsnap/compile_cache/iseq.rb) and disables its `ISeq` compile cache, because a cached instruction sequence would not carry the `Coverage` instrumentation. Bootsnap's other caches (load path, YAML, JSON) are unaffected and keep working.  
 
 ### Debugging Redis Store
 

data/Rakefile

@@ -21,6 +21,22 @@ Rake::TestTask.new(:test) do |test|
   test.verbose = true
 end
 
+###
+# Solid Cache brings a Rails engine with it, which changes how the rest of the
+# suite behaves in the same process. It gets its own task and its own process.
+###
+desc "run the Solid Cache backed adapter tests (SQLite, needs solid_cache)"
+task :"test:solid_cache" do
+  # BUNDLE_WITH opts the optional group onto the load path for this run only.
+  # It has to already be installed: `bundle install --with solid_cache`.
+  sh({"COVERBAND_SOLID_CACHE" => "true", "BUNDLE_WITH" => "solid_cache"},
+    "bundle exec ruby -Ilib -Itest test/coverband/adapters/solid_cache_store_test.rb") do |ok, _res|
+    unless ok
+      abort "solid_cache tests failed. If the gems are missing, run: bundle install --with solid_cache"
+    end
+  end
+end
+
 desc "run the web report's javascript unit tests (node --test)"
 task :"test:javascript" do
   # Pass expanded file paths rather than the bare directory: node's
@@ -51,8 +67,3 @@ desc "start webserver"
 task :server do
   exec "rackup -I lib"
 end
-
-desc "publish gem with 2 factor auth, reminder how"
-task :publish_gem do
-  exec "gem push pkg/coverband-4.2.3.XXX.gem"
-end

data/changes.md

@@ -1,3 +1,62 @@
+### 7.0.0
+
+**Breaking changes**
+
+* **Upgrading from 6.x? Follow [Upgrading to 7.0](https://github.com/danmayer/coverband#upgrading-to-70) in the README**, which lists what to change for each item below. Removed APIs are removed outright rather than deprecated first.
+* **The `redis` gem is no longer a dependency of Coverband. If you use Redis (the default), add `gem "redis"` to your Gemfile when you upgrade.** Redis is still the default store and still needs no other configuration: whenever the `redis` gem is installed Coverband loads it and stores coverage there exactly as before. Apps that only got `redis` through Coverband will otherwise boot with a warning telling them to add it, and record nothing until they do. Apps that store coverage elsewhere (`ActiveSupportCacheStore` with Solid Cache, memcached, or files) no longer need Redis installed at all
+* **Coverage and tracker history do not survive this upgrade.** Stored documents now carry the metadata the new merge protocol needs, and keys are scoped by a generation token, so the storage format version changed for both `RedisStore` and the cache adapters. Old keys are ignored rather than migrated, and coverage accumulates fresh from the upgrade. Delete the old `coverband_3_2.*` keys once you are happy with the new data.
+* **Reporting to coverband.io (`WebServiceStore`) has been removed, as the hosted service is no longer maintained.** This also removes `ViewTrackerService`, loading `config/coverband_service.rb`, the `api_key`, `service_url`, `coverband_timeout`, `service_dev_mode`, `service_test_mode`, and `process_type` settings, and the `COVERBAND_API_KEY`, `COVERBAND_URL`, `COVERBAND_ENABLE_DEV_MODE`, `COVERBAND_ENABLE_TEST_MODE`, and `PROCESS_TYPE` environment variables. Setting `COVERBAND_API_KEY` no longer switches Coverband into service mode. Move settings into `config/coverband.rb` and configure Redis or an `ActiveSupportCacheStore`
+* Removed configuration settings that no longer had production consumers: `reporter` (no effect since 5.0), `s3_region`, `s3_bucket`, `s3_access_key_id`, `s3_secret_access_key`, `track_gems`, `gem_details`, and `simulate_oneshot_lines_coverage`, plus the coverband.io settings above. Assigning any of them logs a warning naming the setting and how to fix it, and is otherwise ignored, so an old `config/coverband.rb` still boots.
+* `Coverband::Utils::SourceFile` and `Coverband::Utils::Result` now accept only enriched file records from stored Coverband reports. Passing the legacy bare line-coverage Array is no longer supported.
+* **`Coverband::Adapters::MemcachedStore` has been removed.** Use `ActiveSupportCacheStore.new(cache, cache_namespace: "...")` with the same memcached cache; it also supports the trackers. `ActiveSupportCacheStore` no longer accepts `memcached_namespace`
+* **`background_reporting_sleep_seconds` now defaults to 600** for the new cache adapter (`HashRedisStore` still defaults to 300, everything else to 60), because each report rewrites a whole document.
+* `Adapters::Base#size` now returns bytes as an Integer or `nil`; `size_in_mib` owns the "N/A" presentation. A store returning the string `"N/A"` previously reported `0.00` MiB.
+* `Adapters::Base#get_coverage_report` now reports the receiver's coverage instead of routing through `Coverband.configuration.store`, which quietly returned another store's data when the receiver was not the configured one.
+* Removed `AbstractTracker#redis_store`; custom trackers use `#storage`. Trackers no longer reach through the store to raw Redis commands.
+* Removed the misspelled `Coverband::Utils::Results#runtime_relavent_lines`; use `#runtime_relevant_lines` instead.
+* Removed `Adapters::Base#raw_store` and the Redis adapters' raw-client escape hatch. Redis maintenance now uses the narrow `store.cleanup` capability (`clear_legacy!` and `clear_orphans!`); adapters that cannot enumerate keys return `nil`.
+* Work is retained when generation resolution fails, so a backend blip during a reporting cycle no longer discards that cycle's coverage. Previously only deltas that had reached the pending queue were protected, and the generation is resolved before the payload is enqueued. The retention caps apply to that held work too, so a sustained outage cannot grow the queue without limit
+* A cache store that is not resolvable yet (`ActiveSupportCacheStore.new { Rails.cache }` running before Rails assigns `Rails.cache`) is no longer a `NoMethodError` on a nil target. It holds the cycle's work, logs, and resolves on a later cycle. A resolver returning something that is not a cache store now names the problem instead of failing deep in the storage layer
+* Rake tasks that reach the store (`coverband:clear`, `clear_coverage`, `clear_tracker`, `clear_legacy`, `clear_orphans`, `coverage`, `coverage_json`, `coverage_html`) load the Rails environment first. With a lazily configured store they previously failed with an unavailable cache unless `rake environment` was named explicitly
+* Coverage data loss (eviction, dropped pending deltas) is now surfaced on the web report index. It was logged and shown on the tracker tabs, but the coverage index reported partial numbers as though they were complete
+* `Adapters::SessionCoverage#save_report` returns the protocol state from `Session#record` rather than `nil`, so a caller can tell a write that landed from one that was deferred or refused
+* Coverage now absorbs the two-cycle outage the design commits to. The cap bounds the queue, and the cycle that recovers takes a slot in it, so a cap of 2 only ever absorbed one; it is now 3
+* Data loss from dropping a delta that was already written and merely awaiting confirmation is reported as `unconfirmed_dropped` rather than `pending_dropped`, and the web report says the numbers may be undercounted instead of claiming earlier results are unavailable. Only the second kind is lost coverage
+* Trackers keep their own keys whenever a report is not stored (`:failed`, `:unavailable`, or an error), so an unreachable backend is no longer lossier for them than one that raises. `TrackerStorage::Base#retains_pending?` is removed; the decision comes from what `record` returns
+* A write refused or errored *after* the delta was enqueued now reports `:retained` rather than `:failed`, since the work is in the storage queue and a caller holding a second copy would replay it. This is the documented memcached >1MB path, where it double counted `QueryBurstTracker`
+* `QueryBurstTracker` reports on a quiet cycle when storage is holding work it could not write, instead of waiting for the next burst to flush it
+* A document that cannot be written is now reported while it is happening, rather than an hour later. Its retention caps never fire on a quiet tracker -- nothing new arrives for them to drop -- so only the absolute age cap eventually turned a permanently refused write (a tracker document past memcached's 1MB limit, for instance) into a loss event, and until then the tab read "0 used" exactly like an app that used none. The web report now says how many reports could not be stored and since when
+* Presence trackers (views, routes, translations) re-supply their known keys when storage reports work dropped at its retention caps, so a backend outage longer than the queue no longer leaves a used view reading as unused. Their merge is idempotent, so this cannot double count; `QueryBurstTracker` sums, so its loss stays irreducible and reported
+* `save_report` no longer mutates the report it is given. The merge used to sum stored counts back into the caller's line arrays, so a caller that reused its report object re-submitted counts that were already recorded.
+
+**Features**
+
+* Replaced the generation lifecycle mixin and its implicit instance-variable/hook contract with a state-owning coordinator and typed generation-change events (#656)
+* Added structured storage health through `Coverband.storage_health`, normal JSON reports, and the MCP `get_storage_health` tool, so monitoring can distinguish healthy, stalled, data-loss, and unsupported diagnostic states (#658)
+* Added `Coverband::Adapters::ActiveSupportCacheStore`, which stores coverage in any `ActiveSupport::Cache::Store` — Redis, Memcached, files, or Solid Cache for Postgres/MySQL/SQLite. The cache target can be passed lazily (`ActiveSupportCacheStore.new { Rails.cache }`) so it works from `config/coverband.rb`, where `Rails.cache` does not exist yet (#533)
+* Trackers (views, routes, translations, query bursts) now work on non-Redis stores. They previously reached through the store to raw Redis commands, so file and memcached users got trackers that silently collected nothing and empty web UI tabs
+* Fixed the read-modify-write conflict Coverband has always had on `RedisStore`: concurrent reports could silently drop one process's contribution. Reports are now applied under a per-writer sequence, so a conflicting write is detected and repaired on the next cycle without double counting. `QueryBurstTracker` had the same conflict on its cumulative counters and is fixed the same way
+* Resets are now strong: `clear!` and `reset_recordings` retire a whole generation key, so a straggling write from before the reset cannot undo it
+* Coverband now detects when a backend has dropped its data (cache eviction, `Rails.cache.clear`) and reports it in the web UI rather than silently showing partial numbers
+* Trackers are skipped with an explanatory log line when the configured store cannot support them, instead of collecting nothing
+* Query bursts no longer count Coverband's own storage queries against the surrounding request, which would otherwise inflate query counts on a database backed cache
+* Added `persistent_coverage?`, `supports_trackers?`, and `supports_paged_reports?` capability predicates on adapters, plus `file_count` and `cached_file_count` defaults so non-Redis stores no longer raise from the web UI's datatables path
+* `redis_ttl` applies to stored coverage documents again; generation pointers deliberately never expire, since a pointer that outlived its document would leave live coverage unreachable
+* Storage reads degrade to empty and log when the backend is unavailable (an unreachable cache, or a Solid Cache table that has not been created yet) rather than raising into the request rendering the report; write failures still reach the reporting paths that log them
+* Added `rake test:solid_cache`, an ENV gated SQLite backed Solid Cache suite covering atomic pointer creation, batched pointer reads, ActiveRecord being unavailable, a missing Solid Cache schema, and Coverband's own SQL not being attributed to the request that triggered the report
+* Added `rake coverband:clear_orphans` to reclaim generation keys no longer referenced by a pointer, and scoped `coverband:clear_legacy` to Coverband's own namespaces and tracker names so it cannot delete unrelated application keys
+* CI now runs a memcached service, so the memcached backed adapter is actually exercised
+* Coverage adapters share one implementation of the merge protocol, and the generation lifecycle is shared between the session and the Redis hash repository, rather than each reimplementing the same bookkeeping
+* The web report has a dark theme. It follows the operating system through `prefers-color-scheme`, so there is nothing to configure and no toggle; every color in `public/application.css` now resolves through a custom property on `:root`, which makes the report restylable from one place. Coverage row colors are picked for contrast on the dark surface rather than darkened mechanically, so covered / missed / never / skipped stay as easy to tell apart; thanks @naofumi-fujii (#665, #666, #667)
+* Added `Coverband::Collectors::TrackerRegistry` so applications and gems can register their own trackers, along with `Coverband::Configuration.add_tracker_flag` for their enablement flags and `Coverband.configuration.tracker_for` / `Coverband.track_key` support for trackers without a dedicated accessor; bundled trackers now self-register and are initialized generically at Rails boot (#651)
+
+**Bug fixes**
+
+* The web report's `/report_json` route and `JSONReport.new(store, as_report: true)` no longer raise `NoMethodError` outside Rails, where ActiveSupport's `as_json` is not loaded; thanks @dajiaohuang (#669)
+* The web report's password check accepts passwords containing `:` (it split the credentials on every colon) and compares in constant time, as does the MCP endpoint's bearer token check. This also drops the runtime dependency on the `base64` gem
+* `Coverband::Utils::Results#respond_to?(name, true)` no longer raises `ArgumentError`
+* The runtime % no longer reads 100% for files with runtime relevant lines that were never hit, and no longer divides by every line of a file that was never eager loaded. It only counts runtime hits on lines that eager loading did not cover, and takes line relevance from real coverage data rather than the never loaded placeholder, which marked blank and comment lines as relevant. Runtime relevant lines on the file page use the same calculation, and the runtime % there is colored by its own value rather than by % covered (#668)
+
 ### 6.2.2
 
 * Feature: Added a dead-code review session to the web report — hide files/folders by hovering any path segment, mark files for deletion with an optional comment, and export marked entries to CSV to drive an out-of-band code-removal process; session state lives in browser localStorage; thanks @obie (#647, #649)