coverband 6.2.1 → 7.0.0.rc.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c47e38934426a369c81dd7d08e5474ad0d8a784b541975c1aa7ee50fc9e2d1ce
-  data.tar.gz: 346c8263e9c961631bcf4af3019d8473177088c5b9ae3cb3844dc7d86bcd7497
+  metadata.gz: 122ec261f93431af71ca87c0113241a9197af2daa07c3d32013b98d893cd3a78
+  data.tar.gz: 785fa634bdba056657cb2b0e358f387decb4aa020faee0f50580dedd929ddcaa
 SHA512:
-  metadata.gz: 907a280ce513b23922b81c44674c135ab067e629ae9f8aaec6eb6a667946a52a85fd1e7a0fe17ee9b24c0a6b81b8b22bcb1e1c53e7ce75ccc7a9c3507b6dd183
-  data.tar.gz: 60198f0536094c5505ea532b238d9d38359f936edb6ea21854c946d3a5f63e7e02b66f1240596b787cad898546a3d48d41595d5d4cab28bb09face2a4f405499
+  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,20 +40,54 @@ 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@v6
+      - uses: actions/checkout@v7
       - uses: ruby/setup-ruby@v1
         with:
           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@v6
+      - uses: actions/checkout@v7
       - uses: ruby/setup-ruby@v1
         with:
           ruby-version: 3.1
           bundler-cache: true # runs 'bundle install' and caches installed gems automatically
       - run: bundle exec standardrb --format github
+  javascript:
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-node@v7
+        with:
+          node-version: "20"
+      - run: node --test test/javascript/*.test.mjs

data/.gitignore

@@ -26,4 +26,5 @@ log/
 test/unique_files
 test/rails7_dummy/tmp
 CLAUDE.md
-.claude/
+.claude/
+scratch/

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:
 
@@ -309,6 +356,110 @@ When enabled, Coverband subscribes to the `render.view_component` notification a
 
 ![image](https://raw.github.com/danmayer/coverband/main/docs/coverband_view_tracker.png)
 
+### Query Burst Tracking
+
+Coverband includes an optional Query Burst Tracker to monitor SQL activity per request and per background job in production. It helps identify potential N+1 query issues and bursty database behavior.
+
+Enable it in your Coverband configuration:
+
+```ruby
+Coverband.configure do |config|
+  config.track_query_bursts = true
+
+  # Thresholds used to flag heavy requests/jobs
+  config.query_burst_query_count_threshold = 30
+  config.query_burst_sql_time_threshold_ms = 100.0
+end
+```
+
+When enabled, Coverband records stats by execution context (for example controller/action and ActiveJob class) and exposes them in the Query Burst Tracker tab in the web UI.
+
+#### Threshold Settings
+
+- `query_burst_query_count_threshold`:
+  - Max SQL query count allowed for a single tracked execution (one request or one job run).
+  - If query count is greater than or equal to this value, it is counted as a threshold hit.
+- `query_burst_sql_time_threshold_ms`:
+  - Max total SQL time (in milliseconds) allowed for a single tracked execution.
+  - If SQL time is greater than or equal to this value, it is counted as a threshold hit.
+
+Threshold logic is OR-based: Coverband records a threshold hit if either threshold is exceeded.
+
+#### What You See in the UI
+
+For each tracked key, the Query Burst Tracker reports:
+
+- Requests: Number of tracked executions
+- Total SQL Calls: Sum of all SQL calls across executions
+- Total SQL ms: Sum of SQL time across executions
+- Max SQL Calls: Highest query count seen in one execution
+- Max SQL ms: Highest SQL time seen in one execution
+- Threshold Hits: Number of executions that exceeded either threshold
+
+#### How To Tune Thresholds
+
+- Start with defaults (`30` queries, `100.0` ms SQL time).
+- Lower thresholds to detect smaller regressions sooner.
+- Raise thresholds if you see too much noise from expected heavy endpoints/jobs.
+- Tune by endpoint/job behavior: latency-sensitive paths often need stricter limits than batch work.
+
+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,
@@ -317,6 +468,24 @@ You can disable the settings view like so:
 
 `config.hide_settings = true`
 
+### Dead-code review session
+
+The web report includes a client-side "dead-code session" toolbar to help drive code-removal work:
+
+- Hide files or whole folders from the report via the ✕ icon that appears when hovering path segments, or hide everything with runtime % > 0 with one toggle.
+- Mark files or folders for deletion via the 🗑 icon (with an optional comment). Marked items disappear from the view and are listed in the "Marked for deletion" modal.
+- Export the marked list as a CSV (`path,comment,marked_at`) to feed a code-removal PR process.
+
+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`.
@@ -382,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.
@@ -393,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.
@@ -491,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
 
@@ -614,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
 
@@ -662,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

@@ -8,7 +8,7 @@ RuboCop::RakeTask.new
 
 task default: %i[test]
 
-task "test:all": %i[test forked_tests benchmarks:memory benchmarks]
+task "test:all": %i[test test:javascript forked_tests benchmarks:memory benchmarks]
 
 task :test
 require "rake/testtask"
@@ -21,6 +21,30 @@ 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
+  # directory-argument handling for --test is inconsistent across versions
+  # (Node 22 fails to find test/javascript/ as a directory in some CI images).
+  sh "node --test #{FileList["test/javascript/*.test.mjs"].join(" ")}"
+end
+
 Rake::TestTask.new(:forked_tests) do |test|
   if RUBY_PLATFORM == "java"
     puts "forked tests not supported on JRuby"
@@ -43,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