rspec-tracer 1.2.3 → 2.0.0.pre.2

data/lib/rspec_tracer/reporters/registry.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+module RSpecTracer
+  # Internal Reporters — see {RSpecTracer} for the user-facing surface.
+  # @api private
+  module Reporters
+    # Orchestrates reporter emission at finalize-time. Called from
+    # `RSpecTracer#run_exit_tasks` once the Engine has persisted its
+    # Snapshot (architectural decision (a): wire from run_exit_tasks,
+    # not Engine-internal). Each configured reporter gets an isolated
+    # rescue; a buggy reporter warns + continues, never propagates a
+    # non-zero exit into the user's test suite.
+    #
+    # Reporter resolution:
+    #   - Configuration#reporters returns `[[name_or_class, opts], ...]`
+    #     when the user called `add_reporter`; `nil` otherwise.
+    #   - When nil, falls back to `DEFAULTS` (`[:terminal, :json]`).
+    #   - Symbol names resolve via `BUILT_INS` to in-tree reporter
+    #     classes. Class values pass through as-is (custom reporters
+    #     conforming to `Reporters::Base`).
+    #   - Unknown symbols raise `ArgumentError` at emit time; the DSL
+    #     validates eagerly, so this is the safety net for programmatic
+    #     callers.
+    class Registry
+      # Symbol -> lazy class-name mapping. Strings (not Class constants)
+      # so the require order doesn't force load of reporter classes
+      # when the Registry module itself is loaded - matches how
+      # `storage_backend`'s Configuration DSL defers backend resolution.
+      BUILT_INS = {
+        terminal: 'RSpecTracer::Reporters::TerminalReporter',
+        json: 'RSpecTracer::Reporters::JsonReporter',
+        html: 'RSpecTracer::Reporters::HtmlReporter'
+      }.freeze
+
+      # Internal constant.
+      # @api private
+      DEFAULTS = %i[terminal json html].freeze
+
+      # Internal helper for the tracer pipeline.
+      # @api private
+      def self.emit_all(configuration:, snapshot:, report_dir:, run_metadata:)
+        new(configuration: configuration).emit_all(
+          snapshot: snapshot, report_dir: report_dir, run_metadata: run_metadata
+        )
+      end
+
+      # Internal method on the tracer pipeline.
+      # @api private
+      def initialize(configuration:)
+        @configuration = configuration
+      end
+
+      # Internal method on the tracer pipeline.
+      # @api private
+      def emit_all(snapshot:, report_dir:, run_metadata:)
+        entries = resolve_entries
+        return [] if entries.empty?
+        return [] if empty_snapshot?(snapshot)
+
+        entries.map { |klass, opts| emit_one(klass, opts, snapshot, report_dir, run_metadata) }
+      end
+
+      private
+
+      # Internal method on the tracer pipeline.
+      # @api private
+      def resolve_entries
+        declared = @configuration.respond_to?(:reporters) ? @configuration.reporters : nil
+        source = declared && !declared.empty? ? declared : DEFAULTS.map { |name| [name, {}] }
+        source.map { |name_or_class, opts| [resolve_class(name_or_class), opts || {}] }
+      end
+
+      # Internal method on the tracer pipeline.
+      # @api private
+      def resolve_class(name_or_class)
+        return name_or_class if name_or_class.is_a?(Class)
+
+        const_name = BUILT_INS.fetch(name_or_class) do
+          raise ArgumentError, "unknown reporter: #{name_or_class.inspect}"
+        end
+
+        Object.const_get(const_name)
+      end
+
+      # Internal method on the tracer pipeline.
+      # @api private
+      def emit_one(klass, opts, snapshot, report_dir, run_metadata)
+        reporter = klass.new(
+          snapshot: snapshot,
+          report_dir: report_dir,
+          run_metadata: run_metadata,
+          logger: logger,
+          **opts
+        )
+        reporter.generate
+      rescue StandardError => e
+        warn_continue(klass, e)
+        nil
+      end
+
+      # Internal method on the tracer pipeline.
+      # @api private
+      def warn_continue(klass, err)
+        logger&.warn("rspec-tracer: reporter #{klass.name} failed (#{err.class}: #{err.message})")
+      end
+
+      # Internal method on the tracer pipeline.
+      # @api private
+      def logger
+        @configuration.respond_to?(:logger) ? @configuration.logger : nil
+      end
+
+      # Internal method on the tracer pipeline.
+      # @api private
+      def empty_snapshot?(snapshot)
+        snapshot.nil? || snapshot.all_examples.nil? || snapshot.all_examples.empty?
+      end
+    end
+  end
+end

data/lib/rspec_tracer/reporters/terminal_reporter.rb

@@ -0,0 +1,264 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module RSpecTracer
+  # Internal Reporters — see {RSpecTracer} for the user-facing surface.
+  # @api private
+  module Reporters
+    # Concise stdout summary printed at finalize-time. Output is
+    # capped at 4 lines for a typical run (5 when duplicate /
+    # interrupted / flaky / pending counters are non-zero). Kind-less
+    # taxonomy by design - the in-memory Input#kind enum does not
+    # survive Storage::Snapshot persistence, so breaking down
+    # "Changed files: Templates / Locales / Ruby" would require a
+    # schema bump (deferred).
+    #
+    # Color policy:
+    #   - Respects `NO_COLOR` per https://no-color.org/ (any value
+    #     disables, even empty string).
+    #   - Emits ANSI codes only when the output stream reports tty?.
+    #   - The header line paints red on any failure / interrupted,
+    #     yellow on pending-only, green otherwise.
+    class TerminalReporter < Base
+      # Internal constant.
+      # @api private
+      COLORS = {
+        reset: 0,
+        red: 31,
+        green: 32,
+        yellow: 33,
+        cyan: 36
+      }.freeze
+      private_constant :COLORS
+
+      # "\u00B7" = U+00B7 MIDDLE DOT. Written as the ASCII escape form
+      # so mutant's US-ASCII-defaulted parser doesn't choke on
+      # non-ASCII bytes in the source file. Same discipline as the
+      # dependency_graph.rb workaround.
+      SEPARATOR = " \u00B7 "
+      private_constant :SEPARATOR
+
+      # Snapshot-set-name => human label pairs for the tally line.
+      # Data-driven to keep tally_line's AbcSize below rubocop's
+      # threshold; new counters go here without growing the method.
+      TALLY_FIELDS = [
+        [:failed_examples, 'failed'],
+        [:pending_examples, 'pending'],
+        [:flaky_examples, 'flaky'],
+        [:interrupted_examples, 'interrupted']
+      ].freeze
+      private_constant :TALLY_FIELDS
+
+      # Internal constant.
+      # @api private
+      BYTES_PER_MIB = 1_048_576.0
+      private_constant :BYTES_PER_MIB
+
+      # Concrete implementation of {RSpecTracer::Reporters::Base#generate}.
+      # Prints a per-run summary to the configured output stream.
+      #
+      # @return [Array<String>, nil] the lines emitted, or nil when the
+      #   run had no examples worth reporting.
+      def generate
+        return nil if no_op?
+
+        lines = build_lines
+        stream = output_stream
+        lines.each { |line| stream.puts line }
+        lines
+      end
+
+      private
+
+      # Internal method on the tracer pipeline.
+      # @api private
+      def build_lines
+        [header_line, tally_line, kind_breakdown_line, cache_line, report_line].compact
+      end
+
+      # Internal method on the tracer pipeline.
+      # @api private
+      def header_line
+        total = snapshot.all_examples.size
+        run = run_count
+        skipped = snapshot.skipped_examples.size
+        cached_pct = cache_percent(total, skipped)
+
+        text = "rspec-tracer: #{total} examples tracked" \
+               "#{SEPARATOR}#{run} re-run#{SEPARATOR}#{skipped} skipped " \
+               "(#{cached_pct}% cached)"
+        paint(header_color, text)
+      end
+
+      # Internal method on the tracer pipeline.
+      # @api private
+      def tally_line
+        parts = TALLY_FIELDS.filter_map do |field, label|
+          ids = snapshot.send(field)
+          "#{ids.size} #{label}" unless ids.empty?
+        end
+        parts << "#{duplicate_count} duplicate" if duplicate_count.positive?
+        return nil if parts.empty?
+
+        paint(:yellow, parts.join(SEPARATOR))
+      end
+
+      # Internal method on the tracer pipeline.
+      # @api private
+      def cache_line
+        path = run_metadata[:cache_path]
+        return nil if path.nil? || path.to_s.empty?
+
+        size_part = cache_size_suffix(path.to_s)
+        "cache: #{path}#{size_part}"
+      end
+
+      # Per-reason breakdown of the run examples (e.g. 12 Files
+      # changed · 5 No cache). Sourced from snapshot.cache_hit_reason
+      # which the engine populated via @filtered_examples.values.tally
+      # at finalize. Empty {} (cold run with no engine cache) suppresses
+      # the line entirely. Sorted by count descending so the
+      # most-impactful reason leads.
+      def kind_breakdown_line
+        reasons = snapshot.cache_hit_reason
+        return nil if reasons.nil? || reasons.empty?
+
+        parts = reasons
+          .sort_by { |_reason, count| -count.to_i }
+          .map { |reason, count| "#{count} #{reason}" }
+        paint(:cyan, "by reason: #{parts.join(SEPARATOR)}")
+      end
+
+      # Bytes -> "12.3 MiB" / "456 KiB" / "789 B" depending on order.
+      # Mirrors JsonBackend#format_mib's MiB-and-up presentation but
+      # collapses small caches to KiB so a fixture spec writing 4 KiB
+      # doesn't display as "0.0 MiB."
+      def format_size_bytes(bytes)
+        return "#{bytes} B" if bytes < 1024
+        return "#{(bytes / 1024.0).round(1)} KiB" if bytes < BYTES_PER_MIB
+
+        "#{(bytes / BYTES_PER_MIB).round(1)} MiB"
+      end
+
+      # `(<size>)` or `(<size>; <delta>)` suffix for the cache line.
+      # Walks the current run-id dir for the size; walks the prior
+      # run-id dir (mtime-newest peer) for the delta. Wrapped in
+      # rescue so a transient FS error never blocks the surrounding
+      # cache_line emission.
+      def cache_size_suffix(cache_path)
+        current_id = snapshot.run_id
+        return '' if current_id.nil? || current_id.to_s.empty?
+
+        current_dir = File.join(cache_path, current_id)
+        return '' unless File.directory?(current_dir)
+
+        current_bytes = directory_size_bytes(current_dir)
+        prior_bytes = previous_run_dir_bytes(cache_path, current_id)
+        format_cache_suffix(current_bytes, prior_bytes)
+      rescue StandardError
+        ''
+      end
+
+      # Internal method on the tracer pipeline.
+      # @api private
+      def format_cache_suffix(current_bytes, prior_bytes)
+        size = format_size_bytes(current_bytes)
+        return " (#{size})" if prior_bytes.nil?
+
+        delta = current_bytes - prior_bytes
+        sign = if delta.positive?
+                 '+'
+               else
+                 (delta.negative? ? '-' : '')
+               end
+        " (#{size}; #{sign}#{format_size_bytes(delta.abs)} vs prev run)"
+      end
+
+      # Internal method on the tracer pipeline.
+      # @api private
+      def directory_size_bytes(dir)
+        Dir[File.join(dir, '**', '*')].sum do |path|
+          File.file?(path) ? File.size(path) : 0
+        end
+      end
+
+      # Internal method on the tracer pipeline.
+      # @api private
+      def previous_run_dir_bytes(cache_path, current_id)
+        peer_dirs = Dir.children(cache_path).filter_map do |name|
+          next if name == current_id || name.start_with?('.')
+
+          full = File.join(cache_path, name)
+          File.directory?(full) ? [full, File.mtime(full).to_f] : nil
+        end
+        return nil if peer_dirs.empty?
+
+        newest_peer = peer_dirs.max_by(&:last).first
+        directory_size_bytes(newest_peer)
+      end
+
+      # Internal method on the tracer pipeline.
+      # @api private
+      def report_line
+        return nil if report_dir.nil? || report_dir.to_s.empty?
+
+        "report: #{File.join(report_dir, JsonReporter::FILENAME)}"
+      end
+
+      # Internal method on the tracer pipeline.
+      # @api private
+      def header_color
+        return :red if snapshot.failed_examples.any? || snapshot.interrupted_examples.any?
+        return :yellow if snapshot.pending_examples.any?
+
+        :green
+      end
+
+      # Internal method on the tracer pipeline.
+      # @api private
+      def run_count
+        snapshot.all_examples.count do |_, meta|
+          meta.is_a?(::Hash) && meta[:execution_result]
+        end
+      end
+
+      # Internal method on the tracer pipeline.
+      # @api private
+      def duplicate_count
+        snapshot.duplicate_examples.size
+      end
+
+      # Internal method on the tracer pipeline.
+      # @api private
+      def cache_percent(total, skipped)
+        return 0 if total.zero?
+
+        ((skipped.to_f / total) * 100).round
+      end
+
+      # Internal method on the tracer pipeline.
+      # @api private
+      def paint(color_key, text)
+        return text unless use_color?
+
+        code = COLORS.fetch(color_key, COLORS[:reset])
+        "\e[#{code}m#{text}\e[#{COLORS[:reset]}m"
+      end
+
+      # Internal method on the tracer pipeline.
+      # @api private
+      def use_color?
+        return false if ENV.key?('NO_COLOR')
+
+        output_stream.respond_to?(:tty?) && output_stream.tty?
+      end
+
+      # Internal method on the tracer pipeline.
+      # @api private
+      def output_stream
+        options[:io] || $stdout
+      end
+    end
+  end
+end

data/lib/rspec_tracer/rspec/README.md

@@ -0,0 +1,73 @@
+# RSpec integration
+
+Glue between the v2 engine and RSpec's runner lifecycle. One file per
+responsibility.
+
+| File | Role |
+|------|------|
+| [`installation.rb`](installation.rb) | Prepends `RunnerHook` + `ReporterHook` onto `RSpec::Core::Runner` / `RSpec::Core::Reporter`. Idempotent. Called once from `RSpecTracer.start`. |
+| [`runner_hook.rb`](runner_hook.rb) | Overrides `run_specs`. Two-pass filter walk: Pass 1 reads `tracks:` metadata + registers per-example glob/env declarations on the engine; Pass 2 asks `Engine#run_example?` for filter decisions. Mutates `RSpec.world` to the filtered set, logs the `RSpec tracer is running N examples` banner. |
+| [`reporter_hook.rb`](reporter_hook.rb) | Overrides `example_started`, `example_finished`, `example_passed`, `example_failed`, `example_pending`. Forwards into `Engine` for dependency attribution; coverage.json emission lives on the dedicated `Reporters::CoverageJsonReporter` finalize path. |
+| [`parallel_tests.rb`](parallel_tests.rb) | `TEST_ENV_NUMBER` + `PARALLEL_TEST_GROUPS` detection, `rspec_tracer.lock` lifecycle, narrator selection for log silencing, last-process merge via `Storage::JsonBackend#merge_from_peers`. |
+| [`metadata.rb`](metadata.rb) | Per-example `tracks:` DSL walker. Reads `tracks: { files: ..., env: ... }` off an example plus every ancestor group, unions the entries (RSpec's default metadata cascade would clobber on shared keys), and returns the merged `{ files:, env: }` for RunnerHook to register with the engine. |
+
+## Load-order contract
+
+`RSpecTracer.start` installs the hooks at require time on the classes,
+not on an already-constructed Runner instance. Any subsequent
+`RSpec::Core::Runner.new` carries `RunnerHook` in its ancestors chain.
+This lets `RSpecTracer.start` run before RSpec has constructed its
+Runner - the 1.x ObjectSpace-based install required mid-boot timing.
+
+The expected user-facing sequence, unchanged:
+
+```ruby
+# spec_helper.rb (no Rails)
+require 'simplecov'      # optional
+SimpleCov.start           # optional
+require 'rspec_tracer'
+RSpecTracer.start
+# application code loads after this point
+```
+
+```ruby
+# rails_helper.rb (Rails)
+require 'simplecov'
+SimpleCov.start
+require_relative '../config/environment'
+require 'rspec_tracer'
+RSpecTracer.start
+```
+
+If coverage has already accumulated before `RSpecTracer.start`, the
+Installation module logs a warn-level line. Users are still free to
+ignore it - the tracer degrades to "attribute whatever we can observe
+from now on".
+
+## Per-example metadata DSL
+
+Annotate a describe / context / example with `tracks: { files: ..., env: ... }`
+to declare additional dependencies that Coverage + IO observation cannot see:
+
+```ruby
+describe 'AdminController',
+         tracks: { files: 'app/policies/**/*.rb', env: 'ROLE_CONFIG' } do
+  it 'gates on the feature flag' do
+    expect(enabled?).to be(true)
+  end
+end
+```
+
+Both keys accept a String glob / env name OR an Array of them. Nested groups
+contribute additively — a child group declaring `tracks: { env: 'X' }` does
+NOT clobber an ancestor's `tracks: { files: 'Y' }`; both contribute to the
+example's dependency set.
+
+Internally: `Metadata.tracks_for(example)` walks `example.example_group
+.parent_groups` plus the example itself and returns the union. `RunnerHook`
+hands that to `Engine#register_tracks`, which resolves file globs to
+`:declared`-kind Inputs and accumulates the env names for the finalize-time
+`env_snapshot.json` write. Warm runs compare the previous run's env_snapshot
+to the current ENV via `Tracker::EnvSnapshot#invalidated_keys` and mark any
+example whose tracked env key drifted as re-runnable
+(`EXAMPLE_RUN_REASON[:env_changed] => "Environment changed"`).

data/lib/rspec_tracer/rspec/installation.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+require 'rspec/core'
+
+require_relative 'reporter_hook'
+require_relative 'runner_hook'
+
+module RSpecTracer
+  # Internal RSpec — see {RSpecTracer} for the user-facing surface.
+  # @api private
+  module RSpec
+    # Prepends RunnerHook + ReporterHook onto RSpec's runner/reporter
+    # classes. Called once from `RSpecTracer.start`.
+    #
+    # 1.x used `ObjectSpace.each_object(::RSpec::Core::Runner)` to find
+    # the already-instantiated runner and prepend onto its singleton
+    # class - forcing start-time ordering (RSpec had to be mid-boot).
+    # 2.0 prepends onto the class itself at require time, so the hooks
+    # apply to every subsequent Runner / Reporter instance.
+    #
+    # Consequence: `RSpecTracer.start` no longer requires RSpec to be
+    # running. As long as `RSpec::Core::Runner` and `RSpec::Core::Reporter`
+    # are loaded (the standard `require 'rspec'` in spec_helper covers
+    # both), install! succeeds. Side effect: the JRuby FULL_TRACE_ENABLED
+    # / object_space_enabled guard that 1.x needed is no longer load-
+    # bearing - prepend doesn't touch ObjectSpace.
+    #
+    # Idempotence: `Module#prepend` is a no-op when the module is already
+    # in the ancestors chain. Double-calling install! is safe.
+    module Installation
+      # `install!` is named for its side effect (prepend the hooks), not
+      # as a predicate - rubocop's Naming/PredicateMethod defaults to
+      # flagging anything that doesn't return a boolean, but the trailing
+      # `true` is the Ruby idiom for "side-effect method ran fine".
+      #
+      # Target classes are parameterized so unit specs can pass anonymous
+      # fresh classes instead of stubbing the real RSpec constants - the
+      # latter collides with RSpec's own reporter finalization at at_exit
+      # time (RSpec::Core::Time vanishes while the outer suite is still
+      # finalizing).
+      # rubocop:disable Naming/PredicateMethod
+      def self.install!(runner_class: ::RSpec::Core::Runner, reporter_class: ::RSpec::Core::Reporter)
+        warn_if_coverage_already_accumulated
+
+        prepend_hook(runner_class, RSpecTracer::RSpec::RunnerHook)
+        prepend_hook(reporter_class, RSpecTracer::RSpec::ReporterHook)
+
+        true
+      end
+      # rubocop:enable Naming/PredicateMethod
+
+      def self.prepend_hook(target_class, hook_module)
+        return if target_class.ancestors.include?(hook_module)
+
+        target_class.prepend(hook_module)
+      end
+
+      # Emit a single warn-level line when the user's spec_helper
+      # triggered substantial application-code loads before calling
+      # `RSpecTracer.start`. The Coverage peek_result is per-file; we
+      # count files that already have at least one executed line. A
+      # non-SimpleCov fresh boot with >10 tracked files is the signal
+      # that app code loaded before the tracer started, which means
+      # boot-set capture misses those files as transitive dependencies.
+      #
+      # Conservative by design: skip the warning when SimpleCov is
+      # running (SimpleCov-first is the documented load order), and
+      # when Coverage hasn't started (defended-library edge case).
+      def self.warn_if_coverage_already_accumulated
+        return unless defined?(::Coverage)
+        return unless ::Coverage.respond_to?(:running?) && ::Coverage.running?
+        return if defined?(::SimpleCov) && ::SimpleCov.running
+
+        accumulated = _count_accumulated_files
+        return if accumulated < 10
+
+        RSpecTracer.logger.warn(
+          "RSpec tracer: coverage has already accumulated for #{accumulated} file(s) " \
+          'before RSpecTracer.start. Expected load order: RSpecTracer.start runs before ' \
+          'any application code (or after SimpleCov.start if using SimpleCov). Dependency ' \
+          'attribution may miss boot-time loads.'
+        )
+      rescue StandardError
+        nil
+      end
+
+      # Internal helper for the tracer pipeline.
+      # @api private
+      def self._count_accumulated_files
+        ::Coverage.peek_result.count do |_, cov|
+          lines = cov.is_a?(::Hash) ? cov[:lines] : cov
+          lines.is_a?(::Array) && lines.any? { |strength| strength.is_a?(::Integer) && strength.positive? }
+        end
+      end
+    end
+  end
+end

data/lib/rspec_tracer/rspec/metadata.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+require 'set'
+
+module RSpecTracer
+  # Internal RSpec — see {RSpecTracer} for the user-facing surface.
+  # @api private
+  module RSpec
+    # Per-example tracking DSL. Reads the `tracks:` metadata key
+    # off an example and its ancestor example groups and emits a
+    # normalized union of declared file globs + env-var names.
+    #
+    # DSL shape (user-facing):
+    #
+    #   RSpec.describe 'AdminController',
+    #                  tracks: { files: 'app/policies/**/*.rb', env: 'ROLE_CONFIG' } do
+    #     ...
+    #   end
+    #
+    # Values for `:files` and `:env` accept either a single String or
+    # an Array of Strings. Nested groups each contribute their own
+    # tracks hash; the union (not the replace) is what the example
+    # inherits. RSpec's built-in metadata cascade uses Hash#merge
+    # which would clobber a parent `tracks:` with a child `tracks:`
+    # on a shared key - almost never the user's intent. `tracks_for`
+    # bypasses the auto-cascade and walks ancestors explicitly.
+    #
+    # Returns `{ files: Set<String>, env: Set<String> }`. Empty sets
+    # when nothing is declared - callers can short-circuit on
+    # `result[:files].empty? && result[:env].empty?` to skip the
+    # attribution/env-snapshot plumbing.
+    #
+    # Pure-function (module-level, no state). Safe to call from the
+    # RunnerHook filter loop without synchronization.
+    module Metadata
+      # Internal constant.
+      # @api private
+      TRACKS_KEY = :tracks
+      # Internal constant.
+      # @api private
+      FILES_KEY = :files
+      # Internal constant.
+      # @api private
+      ENV_KEY = :env
+
+      # Keep methods module-level via `def self.x` (not module_function)
+      # so mutant can observe them - module_function attaches the
+      # methods to an anonymous singleton that Method#source_location
+      # can't trace (memory: feedback_mutation_friendly_modules).
+      def self.tracks_for(example)
+        files = Set.new
+        envs = Set.new
+
+        collect(example.example_group.parent_groups, files, envs)
+        merge_hash(example.metadata[TRACKS_KEY], files, envs)
+
+        { FILES_KEY => files, ENV_KEY => envs }
+      end
+
+      # parent_groups returns outer-first. Walk from outer to inner so
+      # the set-union is order-agnostic anyway; the order is
+      # documented for future readers who need it deterministic.
+      def self.collect(parent_groups, files, envs)
+        parent_groups.reverse_each do |group|
+          merge_hash(group.metadata[TRACKS_KEY], files, envs)
+        end
+      end
+
+      # A `tracks:` value of nil, non-Hash, or an empty Hash contributes
+      # nothing. Non-Hash values are silently ignored - tolerating
+      # user typos over raising is consistent with the rest of the
+      # DSL surface (add_filter, coverage_track_files).
+      def self.merge_hash(tracks, files, envs)
+        return unless tracks.is_a?(Hash)
+
+        normalize(tracks[FILES_KEY]).each { |v| files << v }
+        normalize(tracks[ENV_KEY]).each { |v| envs << v }
+      end
+
+      # String -> [String]; Array -> itself; anything else -> []. nil,
+      # empty-string, and blank values are filtered so
+      # `tracks: { files: '', env: nil }` doesn't inject empty entries
+      # into the attribution set.
+      def self.normalize(value)
+        case value
+        when String
+          value.empty? ? [] : [value]
+        when Array
+          value.map(&:to_s).reject(&:empty?)
+        else
+          []
+        end
+      end
+    end
+  end
+end