rspec-tracer 1.2.2 → 2.0.0.pre.1

data/lib/rspec_tracer/rspec/runner_hook.rb

@@ -0,0 +1,178 @@
+# 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. `fail_on_duplicates=true`
+    #      surfaces via `::Kernel.exit(1)` in `at_exit_behavior`; the
+    #      hook passes `[]` to super so RSpec doesn't execute anything.
+    #   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.running = true
+          RSpecTracer.duplicate_examples = RSpecTracer.fail_on_duplicates
+          super([])
+          return
+        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
+
+      # Internal method on the tracer pipeline.
+      # @api private
+      def _rspec_tracer_duplicates_detected?
+        duplicates = RSpecTracer.engine.duplicate_examples
+        return false if duplicates.empty?
+
+        total = duplicates.sum { |_, entries| entries.count }
+        hashes = duplicates.size
+        RSpecTracer.logger.error(
+          "RSpec tracer detected #{total} duplicate example(s) across #{hashes} identity hash(es)"
+        )
+        true
+      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,68 @@
+# 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
+    end
+  end
+end