rspec-tracer 1.2.3 → 2.0.0.pre.2

data/lib/rspec_tracer/rspec/runner_hook.rb

@@ -0,0 +1,239 @@
+# frozen_string_literal: true
+
+require_relative 'metadata'
+
+module RSpecTracer
+  # Internal RSpec — see {RSpecTracer} for the user-facing surface.
+  # @api private
+  module RSpec
+    # Prepended onto `RSpec::Core::Runner` by
+    # `RSpecTracer::RSpec::Installation.install!`. Replaces the 1.x
+    # `RSpecTracer::RSpecRunner` singleton-class prepend that the
+    # ObjectSpace loop in `setup_rspec?` used to install.
+    #
+    # Responsibilities, in `run_specs` order:
+    #   1. Early-return to `super` if the engine hasn't been set up
+    #      (defensive; keeps the suite green under `RSPEC_TRACER_DISABLE=1`
+    #      or when the user forgot to call `RSpecTracer.start`).
+    #   2. Partition `RSpec.world.filtered_examples` via the engine:
+    #      tracked examples go through identity-hashing + filter decision;
+    #      ignored examples (matched by `Configuration#ignore_spec_files`)
+    #      pass through untouched - RSpec still runs them, but the tracer
+    #      never sees them. Closes #41.
+    #   3. Detect duplicate example identities. Colliding examples are
+    #      dropped from the run (per-example tracking can't attribute
+    #      coverage to two examples sharing one identity hash); the
+    #      rest of the suite still runs. `fail_on_duplicates=true` then
+    #      surfaces a `::Kernel.exit(1)` in `at_exit_behavior`.
+    #   4. Overwrite `RSpec.world.@filtered_examples` +
+    #      `@example_groups` with the filtered set, then log the run
+    #      banner and delegate to `super`.
+    #
+    # The user-visible log line - `RSpec tracer is running N examples
+    # (actual: N, skipped: N)` - is preserved byte-for-byte from 1.x so
+    # cucumber scenarios and CI log parsers keep working.
+    module RunnerHook
+      # Internal method on the tracer pipeline.
+      # @api private
+      def run_specs(example_groups)
+        return super unless RSpecTracer.engine
+
+        actual_count = ::RSpec.world.example_count
+        if _rspec_tracer_no_examples?(actual_count)
+          super
+          return
+        end
+
+        starting = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        filtered_examples_map, filtered_example_groups = _rspec_tracer_build_filter_decision
+
+        if _rspec_tracer_duplicates_detected?
+          RSpecTracer.duplicate_examples = RSpecTracer.fail_on_duplicates
+          filtered_examples_map, filtered_example_groups =
+            _rspec_tracer_drop_duplicate_examples(filtered_examples_map, filtered_example_groups)
+        end
+
+        ::RSpec.world.instance_variable_set(:@filtered_examples, filtered_examples_map)
+        ::RSpec.world.instance_variable_set(:@example_groups, filtered_example_groups)
+
+        current_count = ::RSpec.world.example_count
+        ending = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        elapsed = RSpecTracer::TimeFormatter.format_time(ending - starting)
+
+        RSpecTracer.logger.info <<-EXAMPLES.strip.gsub(/\s+/, ' ')
+          RSpec tracer is running #{current_count} examples (actual: #{actual_count},
+          skipped: #{actual_count - current_count}) (took #{elapsed})
+        EXAMPLES
+
+        RSpecTracer.running = true
+
+        super(filtered_example_groups)
+      end
+
+      private
+
+      # Internal method on the tracer pipeline.
+      # @api private
+      def _rspec_tracer_no_examples?(actual_count)
+        return false unless actual_count.zero?
+
+        RSpecTracer.running = true
+        RSpecTracer.no_examples = true
+      end
+
+      # Two-pass filter-decision walk over RSpec.world.filtered_examples.
+      #
+      # Pass 1 pre-walks every tracked example to compute its identity
+      # hash (Example.from) and register the `tracks:` metadata via
+      # `Engine#register_tracks`. This must complete for every
+      # example before ANY `run_example?` call because the env-
+      # invalidation pass (`Engine#apply_env_filter_decisions`) needs
+      # the full set of tracked env names to classify which examples
+      # re-run. Caching the tracer-example per example.object_id
+      # avoids a second MD5 in Pass 2.
+      #
+      # Between passes, `apply_env_filter_decisions` unions the
+      # env-changed decisions into @filtered_examples so Pass 2's
+      # `run_example?` sees them alongside the file-change decisions
+      # computed at Engine.setup time.
+      #
+      # Pass 2 makes the actual run/skip decisions and tags metadata.
+      # Ignored spec files (Configuration#ignore_spec_files) are
+      # handled in Pass 2 and skip both passes' engine surface -
+      # RSpec still runs them, the tracer never sees them.
+      # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
+      def _rspec_tracer_build_filter_decision
+        to_run = Hash.new { |hash, group| hash[group] = [] }
+        groups = Set.new
+        engine = RSpecTracer.engine
+        tracer_cache = {}.compare_by_identity
+
+        _rspec_tracer_collect_tracks(engine, tracer_cache)
+        engine.apply_env_filter_decisions
+
+        ::RSpec.world.filtered_examples.each_pair do |example_group, examples|
+          examples.each do |example|
+            if RSpecTracer.ignore_spec_file?(example.metadata[:file_path])
+              to_run[example_group] << example
+              groups << example.example_group.parent_groups.last
+              next
+            end
+
+            tracer_example = tracer_cache.fetch(example)
+            example_id = tracer_example[:example_id]
+
+            if engine.run_example?(example_id)
+              run_reason = engine.run_example_reason(example_id)
+              tracer_example[:run_reason] = run_reason
+              example.metadata[:description] = "#{example.description} (#{run_reason})"
+
+              to_run[example_group] << example
+              groups << example.example_group.parent_groups.last
+
+              engine.register_example(tracer_example)
+            else
+              engine.on_example_skipped(example_id)
+            end
+          end
+        end
+
+        engine.deregister_duplicate_examples
+
+        [to_run, groups.to_a]
+      end
+      # rubocop:enable Metrics/AbcSize, Metrics/MethodLength
+
+      def _rspec_tracer_collect_tracks(engine, tracer_cache)
+        ::RSpec.world.filtered_examples.each_pair do |_example_group, examples|
+          examples.each do |example|
+            next if RSpecTracer.ignore_spec_file?(example.metadata[:file_path])
+
+            tracer_example = RSpecTracer::Example.from(example)
+            example_id = tracer_example[:example_id]
+            example.metadata[:rspec_tracer_example_id] = example_id
+            tracer_cache[example] = tracer_example
+
+            tracks = RSpecTracer::RSpec::Metadata.tracks_for(example)
+            next if tracks[:files].empty? && tracks[:env].empty?
+
+            engine.register_tracks(example_id, tracks)
+          end
+        end
+      end
+
+      # Logs the duplicate-identity diagnostic and returns whether any
+      # were found. The summary line keeps its 1.x wording (CI log
+      # parsers + specs match on it); the indented detail names each
+      # colliding example so the user can find and rename them.
+      # @api private
+      def _rspec_tracer_duplicates_detected?
+        duplicates = RSpecTracer.engine.duplicate_examples
+        return false if duplicates.empty?
+
+        total = duplicates.sum { |_, entries| entries.count }
+        RSpecTracer.logger.error(
+          "RSpec tracer detected #{total} duplicate example(s) across " \
+          "#{duplicates.size} identity hash(es). Examples that share one rspec-tracer " \
+          'identity cannot be tracked separately and are dropped from this run - give ' \
+          "them distinct descriptions to fix:\n#{_rspec_tracer_duplicate_report(duplicates)}"
+        )
+        true
+      end
+
+      # The indented per-hash detail block for the duplicate
+      # diagnostic: the identity hash, then one labelled line per
+      # colliding example under it.
+      # @api private
+      def _rspec_tracer_duplicate_report(duplicates)
+        duplicates.map do |example_id, entries|
+          labelled = entries.map { |entry| "    - #{_rspec_tracer_example_label(entry)}" }
+          "  #{example_id}\n#{labelled.join("\n")}"
+        end.join("\n")
+      end
+
+      # `file:line description` for one colliding example, read off the
+      # `Example.from` payload (rerun location preferred, mirroring the
+      # reporter + `explain` columns).
+      # @api private
+      def _rspec_tracer_example_label(entry)
+        file = entry[:rerun_file_name] || entry[:file_name]
+        line = entry[:rerun_line_number] || entry[:line_number]
+
+        "#{file}:#{line} #{entry[:full_description] || entry[:description]}".rstrip
+      end
+
+      # Drops the colliding examples from the filtered run set. The
+      # rest of the suite still runs; `fail_on_duplicates` governs only
+      # the exit code (via `at_exit_behavior`), not whether anything
+      # runs. A group is kept only if it still has examples after the
+      # colliding ones are removed.
+      #
+      # The returned Hash uses the same `Hash.new { |h, k| h[k] = [] }`
+      # default-block shape as `_rspec_tracer_build_filter_decision`'s
+      # `to_run`. That contract matters because rspec-core's
+      # `RSpec::Core::World#example_count` walks `g.descendants` for
+      # every top-level group and reads `e.filtered_examples`
+      # (= `world.filtered_examples[e]`) on each descendant — including
+      # INTERMEDIATE groups (a `describe` that contains only nested
+      # `describe`s, no direct `it`s). A plain Hash returns `nil` for
+      # those keys, which then NPEs in
+      # `inject(0) { |a, e| a + e.filtered_examples.size }`. The
+      # default block returns `[]` (`.size == 0`), matching the
+      # pre-drop path's behavior.
+      # @api private
+      def _rspec_tracer_drop_duplicate_examples(examples_map, example_groups)
+        duplicate_ids = Set.new(RSpecTracer.engine.duplicate_examples.keys)
+
+        kept_map = Hash.new { |hash, group| hash[group] = [] }
+        examples_map.each do |group, examples|
+          survivors = examples.reject do |example|
+            duplicate_ids.include?(example.metadata[:rspec_tracer_example_id])
+          end
+          kept_map[group] = survivors unless survivors.empty?
+        end
+
+        [kept_map, example_groups.select { |group| kept_map.key?(group) }]
+      end
+    end
+  end
+end

data/lib/rspec_tracer/source_file.rb

@@ -1,12 +1,21 @@
 # frozen_string_literal: true
 
 module RSpecTracer
+  # Path manipulation helpers used by Example.location_file_name.
+  # Post-coverage-stack retirement, the only caller is example.rb
+  # (the legacy CoverageReporter that previously used these is gone).
+  #
+  # All methods declared `def self.x` per
+  # feedback_mutation_friendly_modules so mutant observes mutations
+  # through the singleton call path.
   module SourceFile
+    # Internal constant.
+    # @api private
     PROJECT_ROOT_REGEX = Regexp.new("^#{Regexp.escape(RSpecTracer.root)}").freeze
 
-    module_function
-
-    def from_path(file_path)
+    # Internal helper for the tracer pipeline.
+    # @api private
+    def self.from_path(file_path)
       return unless File.file?(file_path)
 
       {
@@ -16,21 +25,29 @@ module RSpecTracer
       }
     end
 
-    def from_name(file_name)
+    # Internal helper for the tracer pipeline.
+    # @api private
+    def self.from_name(file_name)
       from_path(file_path(file_name))
     end
 
-    def file_name(file_path)
+    # Internal helper for the tracer pipeline.
+    # @api private
+    def self.file_name(file_path)
       file_path.sub(PROJECT_ROOT_REGEX, '')
     end
 
-    def file_path(file_name)
+    # Internal helper for the tracer pipeline.
+    # @api private
+    def self.file_path(file_name)
       return file_name if absolute_external_file?(file_name)
 
       File.expand_path(file_name.sub(%r{^/}, ''), RSpecTracer.root)
     end
 
-    def absolute_external_file?(file_name)
+    # Internal helper for the tracer pipeline.
+    # @api private
+    def self.absolute_external_file?(file_name)
       file_name.start_with?('/') &&
         !file_name.start_with?(RSpecTracer.root) &&
         File.file?(file_name)

data/lib/rspec_tracer/storage/README.md

@@ -0,0 +1,35 @@
+# Storage
+
+Persistence layer for the dependency graph and per-example metadata.
+Pluggable via a backend protocol.
+
+## Responsibilities
+
+- Load and save the dependency graph atomically.
+- Enforce `schema_version` — refuse to load a cache outside the supported
+  range. On mismatch: log, discard, fall back to cold boot. No
+  migrators.
+- Never propagate storage errors to the caller — corrupted or missing
+  cache triggers a cold run, not a test-suite failure.
+
+## Public protocol
+
+```ruby
+module RSpecTracer::Storage::Backend
+  def load_graph(schema_version:); end
+  def save_graph(graph, schema_version:); end
+  def transactional_save(&block); end
+end
+```
+
+## Planned backends
+
+- `JsonBackend` — default, human-readable, diff-friendly.
+- `SqliteBackend` — optional, for large suites where JSON load cost
+  dominates.
+
+## Status
+
+Shipping in 2.0. The legacy 1.x persistence files
+(`lib/rspec_tracer/cache.rb`, `report_writer.rb`, `coverage_writer.rb`)
+were retired and replaced by this storage subsystem.

data/lib/rspec_tracer/storage/backend.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+module RSpecTracer
+  # Internal Storage — see {RSpecTracer} for the user-facing surface.
+  # @api private
+  module Storage
+    # Protocol every storage backend must satisfy. JsonBackend is the
+    # default; SqliteBackend is an opt-in alternative on MRI. The
+    # `spec/contracts/storage_backend.rb` shared-examples group asserts
+    # the full contract on every implementation.
+    #
+    # Rationale for the method set (from ARCHITECTURE.md, Contracts
+    # between layers):
+    #   - `load_graph(schema_version:)` returns `Snapshot` or `nil`.
+    #     `nil` means "no cache, or schema mismatch." Never raises on
+    #     corruption - the backend's job is to normalize malformed
+    #     inputs into nil + a log line.
+    #   - `save_graph(snapshot, schema_version:)` persists the graph.
+    #     Either every file lands or none do (atomic via
+    #     transactional_save).
+    #   - `last_run_id` returns the identifier of the most recent
+    #     successful save, or `nil` if no cache exists.
+    #   - `transactional_save(&block)` runs the block with
+    #     single-writer semantics and commits on clean exit; on any
+    #     raise, the pre-block state is preserved.
+    #   - `clear!` removes everything the backend owns.
+    #
+    # This module is intentionally documentation-only - it does not
+    # define stubs that raise NotImplementedError, because mutant
+    # would flag every `raise` as an alive mutation with no way to
+    # kill it. The shared-examples contract is the real gate.
+    #
+    # @example Registering a custom storage backend
+    #   class MyBackend
+    #     def load_graph(schema_version:); end
+    #     def save_graph(snapshot, schema_version:); end
+    #     def last_run_id; end
+    #     def transactional_save(&block); yield; end
+    #     def clear!; end
+    #   end
+    #
+    #   RSpecTracer.configure do
+    #     storage_backend MyBackend.new
+    #   end
+    module Backend
+      # Internal constant.
+      # @api private
+      REQUIRED_METHODS = %i[
+        load_graph
+        save_graph
+        last_run_id
+        transactional_save
+        clear!
+      ].freeze
+
+      # Verifies a candidate object satisfies the backend protocol.
+      # Used by {RSpecTracer::Configuration#storage_backend} to gate
+      # custom-backend registration at config-load time.
+      #
+      # @param backend [Object] candidate backend instance
+      # @return [Boolean] true if every {REQUIRED_METHODS} entry is
+      #   responded to
+      def self.conforms?(backend)
+        REQUIRED_METHODS.all? { |m| backend.respond_to?(m) }
+      end
+
+      # Construct the configured storage backend instance. Single
+      # source of truth for the json/sqlite dispatch + sqlite-gem-
+      # missing graceful fallback to :json, used by both
+      # {RSpecTracer::Engine} (runtime) and the
+      # {RSpecTracer::CLI::CacheInfo} / {RSpecTracer::CLI::Explain}
+      # sub-commands (post-run inspection). Pre-refactor, the
+      # dispatch lived only on Engine and the CLI sub-commands
+      # hardcoded the JsonBackend on-disk layout — so
+      # `bin/rspec-tracer cache:info` / `explain` reported "no
+      # last_run.json" even when `storage_backend :sqlite` had
+      # persisted a working cache.
+      #
+      # @param cache_path [String] root cache directory.
+      # @param configuration [Object] anything responding to the
+      #   `storage_backend` / `storage_backend_opts` /
+      #   `cache_retention_local_count` / `cache_size_warn_*` /
+      #   `logger` accessors (defaults to the {RSpecTracer}
+      #   top-level module).
+      # @return [Object] a backend instance satisfying {REQUIRED_METHODS}.
+      def self.build(cache_path:, configuration: RSpecTracer)
+        case configuration.storage_backend
+        when :sqlite
+          build_sqlite(cache_path: cache_path, configuration: configuration)
+        else
+          build_json(cache_path: cache_path, configuration: configuration)
+        end
+      end
+
+      # Internal helper for the tracer pipeline.
+      # JsonBackend / SqliteBackend constants are pre-required by
+      # every call site that loads {Backend} — Engine at gem-boot
+      # time, CLI sub-commands at their own require chain — so the
+      # method body stays focused on the construction shape mutant
+      # can actually verify. Returning a `require_relative` call to
+      # the method would be a structurally-unkillable mutation
+      # (Ruby caches requires; the test process always has both
+      # backends loaded).
+      # @api private
+      def self.build_json(cache_path:, configuration:)
+        JsonBackend.new(
+          cache_path: cache_path,
+          logger: configuration.logger,
+          retention_local_count: configuration.cache_retention_local_count,
+          warn_per_file_mb: configuration.cache_size_warn_per_file_mb,
+          warn_total_mb: configuration.cache_size_warn_total_mb,
+          serializer: configuration.storage_backend_opts[:serializer] || :json
+        )
+      end
+
+      # Internal helper for the tracer pipeline.
+      # See {build_json} for why the SqliteBackend require is at the
+      # call site rather than inside the method body.
+      # @api private
+      def self.build_sqlite(cache_path:, configuration:)
+        SqliteBackend.new(cache_path: cache_path, logger: configuration.logger)
+      rescue SqliteBackend::SqliteBackendError => e
+        configuration.logger.warn(
+          "rspec-tracer: sqlite backend unavailable (#{e.message}); falling back to :json"
+        )
+        build_json(cache_path: cache_path, configuration: configuration)
+      end
+    end
+  end
+end