branchproof 0.9.0 → 0.10.0

data/lib/branchproof/rails_support.rb

@@ -1,12 +1,22 @@
 # frozen_string_literal: true
 
+require "rubygems/version"
+
+# Rails policy validation intentionally stays in one adapter-neutral module.
+# rubocop:disable Metrics/ModuleLength, Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
+
 module Branchproof
   # Boots the selected Rails application after Branchproof's load hook is active.
   module RailsSupport
+    SUPPORTED_RAILS = Gem::Version.new("8.1").freeze
+    SUPPORTED_RSPEC_RAILS_MAJOR = 8
+    SUPPORTED_CAPYBARA_DRIVER = "rack_test"
+
     class Error < StandardError; end
 
     module_function
 
+    # Boot the Rails application for the native Minitest adapter.
     def boot(project:)
       environment = environment_path(project)
       raise Error, "Rails project is missing #{environment}" unless File.file?(environment)
@@ -26,6 +36,9 @@ module Branchproof
       File.join(root, "config", "environment.rb")
     end
 
+    # Require the application and validate the process-wide Rails policy.
+    # This method is public so adapter-specific helpers can own the remaining
+    # test framework setup while sharing the exact same Rails boot checks.
     def boot_environment(environment)
       require environment
       validate_application!
@@ -43,6 +56,90 @@ module Branchproof
       nil
     end
 
+    # Validate the seam after an RSpec Rails helper has loaded. RSpec owns
+    # requiring rspec/rails and configuring its example groups; this method
+    # only checks that that setup is attached to the same, already-validated
+    # Rails application.
+    def validate_rspec!(project:)
+      # A focused spec_helper-only run may live in a Rails project without
+      # loading Rails. Once Rails is loaded, all boot checks still apply.
+      return nil unless defined?(Rails)
+
+      kind = project[:kind] || project["kind"]
+      raise Error, "Rails was loaded for a non-Rails project" if kind.to_s != "rails"
+
+      validate_application!
+      raise Error, "RSpec Rails was not loaded; require rspec/rails from rails_helper" unless defined?(RSpec::Rails)
+
+      expected_root = File.expand_path(project.fetch(:root).to_s)
+      actual_root = Rails.root && File.expand_path(Rails.root.to_s)
+      if actual_root != expected_root
+        raise Error,
+              "Rails application root #{actual_root.inspect} does not match project root #{expected_root.inspect}"
+      end
+
+      rails_metadata = metadata.merge(rspec_rails_version: rspec_rails_version)
+      validate_version_tuple!(rails_metadata)
+      install_rspec_driver_guard!
+      rails_metadata
+    end
+
+    def install_rspec_driver_guard!
+      return unless defined?(Capybara::Session)
+      return if Capybara::Session.instance_variable_defined?(:@branchproof_driver_guard)
+
+      support = self
+      Capybara::Session.prepend(Module.new do
+        define_method(:initialize) do |driver, *args, &block|
+          begin
+            support.validate_rspec_driver!(driver: driver)
+          rescue Branchproof::RailsSupport::Error => e
+            adapter = (Branchproof::RSpecAdapter.active_adapter if defined?(Branchproof::RSpecAdapter))
+            adapter ? adapter.reject_execution!(e.message) : raise
+          end
+          super(driver, *args, &block)
+        end
+      end)
+      Capybara::Session.instance_variable_set(:@branchproof_driver_guard, true)
+    end
+
+    # RSpec Rails invokes this at example execution time, before the example
+    # can ask Capybara to launch a browser. The adapter converts this explicit
+    # rejection into an incomplete/error execution result.
+    def validate_rspec_driver!(example_metadata)
+      metadata = example_metadata.respond_to?(:to_h) ? example_metadata.to_h : {}
+      driver = metadata[:driver] || metadata["driver"]
+      threaded = metadata[:threaded] || metadata["threaded"] || metadata[:parallel] || metadata["parallel"]
+      unsupported = metadata[:js] == true || metadata["js"] == true || threaded ||
+                    (driver && driver.to_s != SUPPORTED_CAPYBARA_DRIVER)
+      return true unless unsupported
+
+      selected = driver || (threaded ? "threaded" : "browser")
+      raise Error, "unsupported RSpec driver #{selected.inspect}; only in-process rack_test is supported"
+    end
+
+    def validate_version_tuple!(rails_metadata)
+      rails_version = Gem::Version.new(rails_metadata.fetch(:rails_version).to_s)
+      ruby_version = Gem::Version.new(rails_metadata.fetch(:ruby_version).to_s)
+      rspec_version = Gem::Version.new(rails_metadata.fetch(:rspec_rails_version).to_s)
+      return true if rails_version.segments.first(2) == SUPPORTED_RAILS.segments.first(2) &&
+                     ruby_version.segments.first(2) == [3, 4] &&
+                     rspec_version.segments.first == SUPPORTED_RSPEC_RAILS_MAJOR
+
+      raise Error,
+            "unsupported Rails/Ruby/RSpec Rails tuple: Rails #{rails_version}, Ruby #{ruby_version}, " \
+            "RSpec Rails #{rspec_version} (supported Rails 8.1, Ruby 3.4.x, RSpec Rails 8.x)"
+    end
+
+    def rspec_rails_version
+      require "rspec/rails/version" if defined?(RSpec::Rails) && !defined?(RSpec::Rails::Version::STRING)
+      return RSpec::Rails::Version::STRING if defined?(RSpec::Rails::Version::STRING)
+      return RSpec::Rails::VERSION if defined?(RSpec::Rails::VERSION)
+      return Gem.loaded_specs.fetch("rspec-rails").version.to_s if Gem.loaded_specs.key?("rspec-rails")
+
+      "unknown"
+    end
+
     def rails_application
       if defined?(Rails) && Rails.respond_to?(:application) && Rails.application
         application = Rails.application
@@ -68,7 +165,11 @@ module Branchproof
 
     def metadata
       { rails_version: Rails::VERSION::STRING,
+        ruby_version: RUBY_VERSION,
+        environment: Rails.env.to_s,
+        reloading: reloading_enabled?(rails_application.config),
         serial_policy: { mode: "single_process", workers: 1, parallel_workers: 1 } }
     end
   end
 end
+# rubocop:enable Metrics/ModuleLength, Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity

data/lib/branchproof/report.rb

@@ -118,6 +118,16 @@ module Branchproof
       0
     end
 
+    def rerun_command(test_id)
+      test = test_records_by_id[test_id.to_s]
+      return unless test && value(test, :adapter).to_s == "rspec"
+
+      selector = value(test, :example_id).to_s
+      return if selector.empty?
+
+      "bundle exec rspec '#{selector.gsub("'", %q('"'"'))}'"
+    end
+
     private
 
     def json_document
@@ -507,10 +517,17 @@ module Branchproof
     end
 
     def baseline_test_counts
+      noun = rspec_run? ? "examples" : "tests"
       executed = value(@baseline, :executed_tests)
       failed = value(@baseline, :failed_tests) || value(@baseline, :failures) || 0
       skipped = value(@baseline, :skipped_tests) || value(@baseline, :skips) || 0
-      "#{executed || 0} tests, #{failed} failed, #{skipped} skipped"
+      "#{executed || 0} #{noun}, #{failed} failed, #{skipped} skipped"
+    end
+
+    def rspec_run?
+      framework = value(@run_metadata, :framework) || value(@run_metadata, :project_framework) ||
+                  value(@baseline, :framework)
+      framework.to_s.downcase == "rspec"
     end
 
     def terminal_coverage_label
@@ -584,6 +601,9 @@ module Branchproof
              end
       return short_id(id) if name.empty? || name == id
 
+      command = rerun_command(id)
+      return "#{name} (rerun: #{command})" if command
+
       duplicates = test_records_by_name[name]
       return name if duplicates.length == 1
 

data/lib/branchproof/rspec_adapter.rb

@@ -0,0 +1,423 @@
+# frozen_string_literal: true
+
+require_relative "records" unless defined?(Branchproof::Records)
+
+module Branchproof
+  # Bridges one serial RSpec run to Runtime lifecycle ownership.
+  class RSpecAdapter
+    # Identifies runner capabilities that cannot produce supported evidence.
+    class UnsupportedRunner < ArgumentError
+      def diagnostic_code = "unsupported_runner"
+    end
+
+    # Restores CLI directory discovery when RSpec runs inside the worker.
+    module DefaultDiscovery
+      def configure(configuration)
+        options[:files_or_directories_to_run] = [options[:default_path] || configuration.default_path].compact
+        super
+      end
+    end
+
+    # Rejects additional class-level runner entry points.
+    module ClassRunnerGuard
+      def run(*args, &)
+        RSpecAdapter.runner_adapter&.reject_execution!("nested or repeated RSpec runs are unsupported")
+        super
+      end
+    end
+
+    # Allows only the worker-owned native runner instance.
+    module RunnerGuard
+      def run(*args, &)
+        RSpecAdapter.runner_adapter&.enter_runner!(self)
+        super
+      end
+    end
+
+    # Assigns observation phases while the reporter owns test registration.
+    module ExampleLifecycle
+      def run(*args, &)
+        adapter = RSpecAdapter.active_adapter
+        return super unless adapter
+
+        adapter.send(:begin_example, self)
+        super
+      ensure
+        adapter&.send(:unattributed)
+      end
+
+      private
+
+      def run_before_example(*args, &)
+        adapter = RSpecAdapter.active_adapter
+        adapter&.send(:begin_attempt, self)
+        result = super
+        adapter&.send(:phase, self, "body")
+        result
+      end
+
+      def run_after_example(*args, &)
+        RSpecAdapter.active_adapter&.send(:phase, self, "teardown")
+        super
+      end
+    end
+
+    # Keeps group-level hooks outside individual example ownership.
+    module ContextLifecycle
+      def run_before_context_hooks(*args, &)
+        adapter = RSpecAdapter.active_adapter
+        return super unless adapter
+
+        adapter.send(:without_owner) { super }
+      end
+
+      def run_after_context_hooks(*args, &)
+        adapter = RSpecAdapter.active_adapter
+        return super unless adapter
+
+        adapter.send(:without_owner) { super }
+      end
+    end
+
+    class << self
+      attr_accessor :active_adapter, :runner_adapter
+    end
+
+    FORBIDDEN_OPTIONS = {
+      dry_run: "dry-run",
+      bisect: "bisect",
+      drb: "DRb",
+      runner: "custom runner"
+    }.freeze
+
+    attr_reader :tests, :late_execution_error
+
+    def initialize(runtime:)
+      @runtime = runtime
+      @tests = {}
+      @example_records = {}.compare_by_identity
+      @file_digests = {}
+      @running = false
+      @completed = false
+      @completion_started = false
+      @registered = false
+      @current_context = nil
+    end
+
+    # rubocop:disable-next Metrics/ParameterLists
+    def run(test_files:, runner_args:, on_complete:, before_load: nil, after_load: nil,
+            test_selection_explicit: false)
+      raise ArgumentError, "test_files must be an Array" unless test_files.is_a?(Array)
+      raise ArgumentError, "runner_args must be an Array" unless runner_args.is_a?(Array)
+      raise ArgumentError, "on_complete must respond to call" unless on_complete.respond_to?(:call)
+      raise UnsupportedRunner, "RSpec adapter cannot run more than once" if @running || @registered
+      raise UnsupportedRunner, "nested RSpec runs are unsupported" if self.class.active_adapter
+      raise UnsupportedRunner, "TEST_ENV_NUMBER is unsupported" if ENV.key?("TEST_ENV_NUMBER")
+
+      require "rspec/core"
+      require "rspec/core/runner"
+      unless Gem::Requirement.new("~> 3.13.0").satisfied_by?(Gem::Version.new(RSpec::Core::Version::STRING))
+        raise UnsupportedRunner, "unsupported RSpec version #{RSpec::Core::Version::STRING}; use 3.13.x"
+      end
+
+      RSpec::Core::Runner.disable_autorun!
+      options = RSpec::Core::ConfigurationOptions.new(runner_args)
+      configured_files = Array(options.options[:files_or_directories_to_run]).map(&:to_s)
+      if test_selection_explicit && configured_files.any?
+        raise ArgumentError, "explicit test selection conflicts with configured RSpec selectors"
+      end
+
+      options.options[:files_or_directories_to_run] = test_files.map(&:to_s) if test_selection_explicit
+      options.singleton_class.prepend(DefaultDiscovery) if !test_selection_explicit && configured_files.empty?
+      reject_options!(options)
+
+      @running = true
+
+      @registered = true
+      @completion_callback = on_complete
+      @unmatched_test_selection = test_selection_explicit && test_files.empty?
+      if @unmatched_test_selection
+        complete(status: 0, finalized: true)
+        return 0
+      end
+      self.class.active_adapter = self
+      self.class.runner_adapter = self
+      install_lifecycle_hooks
+      install_runner_guard
+      runner = RSpec::Core::Runner.new(options)
+      @native_runner = runner
+      adapter = self
+      runner.define_singleton_method(:setup) do |*setup_args|
+        super(*setup_args)
+        return if world.wants_to_quit
+
+        adapter.validate_runner!
+        after_load&.call
+        adapter.send(:install_reporter_listener, configuration.reporter)
+      end
+      before_load&.call
+      status = runner.run($stderr, $stdout)
+      capture_runner_state(runner)
+      complete(status: status, finalized: true)
+      status
+    rescue StandardError => e
+      raise unless @running
+      raise if @completion_started
+
+      @run_error = e
+      capture_runner_state(runner) if runner
+      status = 2
+      complete(status: status, finalized: false)
+      status
+    ensure
+      if self.class.active_adapter.equal?(self)
+        unattributed
+        self.class.active_adapter = nil
+      end
+      @running = false
+    end
+
+    def validate_runner!
+      return nil unless defined?(RSpec.configuration)
+
+      configuration = RSpec.configuration
+      reject_configuration!(configuration)
+      if configuration.respond_to?(:parallelize) && configuration.parallelize
+        raise UnsupportedRunner,
+              "parallel test scheduling is unsupported"
+      end
+
+      nil
+    end
+
+    def example_started(notification)
+      example = notification.example
+      record = test_record(example)
+      record[:status] = "running"
+      register_test(record)
+    end
+
+    def example_finished(notification)
+      example = notification.example
+      record = test_record(example)
+      record[:name] = example.full_description.to_s
+      record[:status] = status_for(example)
+      register_test(record)
+    end
+
+    def reject_execution!(message)
+      @run_error ||= UnsupportedRunner.new(message)
+      @late_execution_error = @run_error if @completion_started
+      raise @run_error
+    end
+
+    def enter_runner!(runner)
+      unless runner.equal?(@native_runner) && !@runner_entered
+        reject_execution!("nested or repeated RSpec runs are unsupported")
+      end
+      @runner_entered = true
+    end
+
+    private
+
+    def capture_runner_state(runner)
+      @selected_test_files = runner.configuration.loaded_spec_files.map { |path| File.expand_path(path.to_s) }
+      @selected_example_ids = runner.world.filtered_examples.values.flatten.map(&:id)
+      @seed = runner.configuration.seed
+      @non_example_failure = runner.world.non_example_failure
+    end
+
+    def reject_options!(options)
+      FORBIDDEN_OPTIONS.each do |key, label|
+        value = options.options[key]
+        next unless value && value != false && value != []
+
+        raise UnsupportedRunner, "#{label} is unsupported"
+      end
+    end
+
+    def reject_configuration!(configuration)
+      if configuration.respond_to?(:dry_run?) && configuration.dry_run?
+        raise UnsupportedRunner,
+              "dry-run is unsupported"
+      end
+      raise UnsupportedRunner, "bisect is unsupported" if configuration.respond_to?(:bisect) && configuration.bisect
+      raise UnsupportedRunner, "DRb is unsupported" if defined?(DRb) && RSpec::Core::Runner.send(:running_in_drb?)
+    end
+
+    def install_reporter_listener(reporter)
+      @defined_example_count = RSpec.world.filtered_examples.keys.sum { |group| group.examples.length }
+      listener = self
+      reporter.register_listener(listener, :example_started, :example_finished)
+    end
+
+    def install_runner_guard
+      return if RSpec::Core::Runner.singleton_class.instance_variable_defined?(:@branchproof_runner_guard)
+
+      RSpec::Core::Runner.singleton_class.prepend(ClassRunnerGuard)
+      RSpec::Core::Runner.prepend(RunnerGuard)
+      RSpec::Core::Runner.singleton_class.instance_variable_set(:@branchproof_runner_guard, true)
+    end
+
+    def install_lifecycle_hooks
+      return if RSpec::Core::Example.instance_variable_defined?(:@branchproof_lifecycle_hooks)
+
+      RSpec::Core::Example.prepend(ExampleLifecycle)
+      RSpec::Core::ExampleGroup.singleton_class.prepend(ContextLifecycle)
+      RSpec::Core::Example.instance_variable_set(:@branchproof_lifecycle_hooks, true)
+    end
+
+    def begin_example(example)
+      validate_runner!
+      seen = (@seen_examples ||= {}.compare_by_identity)
+      reject_execution!("repeated RSpec example attempts are unsupported") if seen[example]
+
+      seen[example] = true
+      phase(example, "setup")
+    rescue ArgumentError => e
+      reject_execution!(e.message)
+    end
+
+    def begin_attempt(example)
+      @attempts ||= {}
+      id = test_id(example)
+      if @attempts[id]
+        @run_error ||= UnsupportedRunner.new("repeated RSpec example attempts are unsupported")
+        raise @run_error
+      end
+      @attempts[id] = true
+    end
+
+    def without_owner
+      previous = @current_context
+      unattributed
+      yield
+    ensure
+      @current_context = previous
+      @runtime.context(test_id: previous&.first, phase: previous&.last || "unattributed")
+    end
+
+    def status_for(example)
+      result = example.execution_result
+      status = result.status&.to_sym
+      return "failed" if (result.respond_to?(:pending_fixed?) && result.pending_fixed?) ||
+                         (example.respond_to?(:pending?) && example.pending? && status == :failed)
+      return "failed" if status == :failed
+      return "skipped" if example.respond_to?(:skipped?) && example.skipped?
+      return "skipped" if status == :pending
+
+      status == :passed ? "passed" : "running"
+    end
+
+    def test_record(example)
+      @example_records[example] ||= begin
+        source = source_for(example)
+        id = Branchproof::Records.id(adapter: "rspec", example_id: example.id.to_s, source: source)
+        @tests[id] = {
+          id: id, adapter: "rspec", name: example.full_description.to_s,
+          example_id: example.id.to_s, class_name: nil, method_name: nil,
+          spec_digest: file_digest(example.id.to_s.sub(/\[[\d:]+\]\z/, "")),
+          source_digest: file_digest(source[:path]),
+          source: source, status: "running", phase_counts: {}
+        }
+      end
+    end
+
+    def test_id(example)
+      test_record(example)[:id]
+    end
+
+    def file_digest(path)
+      expanded = File.expand_path(path)
+      return @file_digests[expanded] if @file_digests.key?(expanded)
+
+      @file_digests[expanded] = File.file?(expanded) ? Digest::SHA256.file(expanded).hexdigest : nil
+    end
+
+    def source_for(example)
+      path = example.metadata[:absolute_file_path] || example.file_path
+      { path: File.expand_path(path.to_s), line: example.metadata[:line_number].to_i }
+    end
+
+    def phase(example, name)
+      id = test_id(example)
+      @current_context = [id, name]
+      @runtime.context(test_id: id, phase: name)
+    end
+
+    def unattributed
+      @current_context = nil
+      @runtime.context(test_id: nil, phase: "unattributed")
+    end
+
+    def register_test(test)
+      @runtime.register_test(test: test)
+    end
+
+    def complete(status:, finalized:)
+      return if @completed || @completion_started
+
+      @completion_started = true
+      apply_canonical_phase_counts
+      tests = @tests.values
+      failed = tests.count { |test| test[:status] == "failed" }
+      skipped = tests.count { |test| test[:status] == "skipped" }
+      diagnostics = completion_diagnostics(status)
+      errored = diagnostics.any? { |diagnostic| diagnostic[:severity] == "error" }
+      result = {
+        status: if errored
+                  "ERROR"
+                elsif tests.empty?
+                  "INCOMPLETE"
+                elsif failed.zero?
+                  "PASSED"
+                else
+                  "FAILED"
+                end,
+        executed_tests: tests.length, failed_tests: failed, skipped_tests: skipped,
+        exit_status: status.to_i, finalized: finalized && !errored, seed: @seed, diagnostics: diagnostics,
+        selected_test_files: @selected_test_files || [], selected_example_ids: @selected_example_ids || [], tests: tests
+      }
+      @completion_callback.call(result)
+      @completed = true
+    end
+
+    def completion_diagnostics(native_status)
+      if @run_error
+        code = if defined?(Branchproof::RailsSupport::Error) && @run_error.is_a?(Branchproof::RailsSupport::Error)
+                 "rails_boot"
+               elsif @run_error.respond_to?(:diagnostic_code)
+                 @run_error.diagnostic_code
+               else
+                 "rspec_run"
+               end
+        return [{ code: code, severity: "error", message: "#{@run_error.class}: #{@run_error.message}" }]
+      end
+      if @non_example_failure || @tests.values.any? { |test| test[:status] == "running" } ||
+         (native_status.to_i != 0 && @tests.values.none? { |test| test[:status] == "failed" })
+        return [{ code: "rspec_run", severity: "error",
+                  message: "RSpec failed outside examples; see runner output" }]
+      end
+
+      return [] unless @tests.empty?
+
+      code, message = if @unmatched_test_selection
+                        ["unmatched_test_selection", "No files matched --test; check the path or glob"]
+                      elsif @defined_example_count.to_i.positive?
+                        ["empty_example_selection",
+                         "RSpec filters selected zero examples; check tags, descriptions, and selectors"]
+                      else
+                        ["empty_suite", "RSpec discovered no examples; check the default path and configured patterns"]
+                      end
+      [{ code: code, severity: "warning", message: message }]
+    end
+
+    def apply_canonical_phase_counts
+      canonical_by_id = @runtime.test_phase_counts
+      @tests.each do |id, test|
+        counts = canonical_by_id[id]
+        test[:phase_counts] = counts unless counts.nil?
+      end
+    end
+  end
+end

data/lib/branchproof/runtime.rb

@@ -107,6 +107,10 @@ module Branchproof
         nil
       end
 
+      def test_phase_counts
+        @evidence.test_phase_counts
+      end
+
       def snapshot
         if @evidence.respond_to?(:snapshot)
           result = @evidence.snapshot

data/lib/branchproof/saved_report.rb

@@ -638,7 +638,9 @@ module Branchproof
     end
 
     def validate_test(test)
-      %w[name class_name method_name source_path].each { |field| validate_string_field(test, field, nullable: true) }
+      %w[adapter name class_name method_name source_path example_id].each do |field|
+        validate_string_field(test, field, nullable: true)
+      end
       validate_integer_field(test, "line", nullable: true)
       phase_counts = test["phase_counts"]
       if phase_counts
@@ -726,7 +728,12 @@ module Branchproof
       string_fields.each do |field|
         fail_with("run_metadata #{field} must be a string") if metadata.key?(field) && !metadata[field].is_a?(String)
       end
-      array_fields = %w[source_patterns test_patterns test_files runner_args]
+      nullable_string_fields = %w[framework framework_version rspec_rails_version rails_version]
+      nullable_string_fields.each do |field|
+        fail_with("run_metadata #{field} must be a string") if metadata.key?(field) &&
+                                                               !metadata[field].nil? && !metadata[field].is_a?(String)
+      end
+      array_fields = %w[source_patterns test_patterns test_files runner_args selected_test_files selected_example_ids]
       array_fields.each do |field|
         if metadata.key?(field) && !strings?(metadata[field])
           fail_with("run_metadata #{field} must be an array of strings")

data/lib/branchproof/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Branchproof
-  VERSION = "0.9.0"
+  VERSION = "0.10.0"
 end