branchproof 0.8.0 → 0.10.0

data/lib/branchproof/iteration_instrumentation.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module Branchproof
+  # Keep matching and iteration in the original lexical scope.
+  module IterationInstrumentation
+    private
+
+    # rubocop:disable Metrics/MethodLength
+    def render_flow(bytes, decision, nested, encloses)
+      metadata = decision.fetch(:instrumentation)
+      case metadata[:type]
+      when "iteration"
+        render_iteration(bytes, decision, nested, encloses)
+      when "required_pattern"
+        expression = render_children(bytes, decision[:byte_start], decision[:byte_length], nested, encloses)
+        runtime = self.class::RUNTIME
+        identifier = decision[:id].inspect
+        "(begin; #{runtime}.enter(#{identifier}); begin; #{expression}; " \
+          "#{runtime}.flow_select(#{identifier}, 0); nil; rescue ::NoMatchingPatternError; " \
+          "#{runtime}.flow_select(#{identifier}, 1); raise; ensure; #{runtime}.leave(#{identifier}); end; end)"
+      else
+        super
+      end
+    end
+
+    # rubocop:enable Metrics/MethodLength
+
+    # rubocop:disable-next Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity -- nested exception callback seam
+    def render_iteration(bytes, decision, nested, encloses)
+      metadata = decision.fetch(:instrumentation)
+      identifier = decision[:id].inspect
+      runtime = self.class::RUNTIME
+      alternative_count = metadata[:lazy] ? 1 : 2
+      marker = "#{runtime}.flow_iteration_callback(#{identifier}, #{alternative_count})"
+      suffix = metadata[:empty] ? "nil; " : ""
+      callback = "; #{marker}; #{suffix}"
+      exception_child = nested.find do |child|
+        child[:instrumentation]&.fetch(:type, nil) == "exception" &&
+          child[:instrumentation].fetch(:implicit, false) &&
+          contains?(child[:byte_start], child[:byte_length], metadata[:insert_at], 0)
+      end
+      if exception_child
+        instrumentation = exception_child.fetch(:instrumentation)
+        callback_child = exception_child.merge(instrumentation: instrumentation.merge(
+          iteration_callback: { insert_at: metadata[:insert_at], text: callback }
+        ))
+        nested = nested.map { |child| child.equal?(exception_child) ? callback_child : child }
+        encloses = encloses.merge(callback_child => encloses[exception_child])
+      end
+      edits = exception_child ? [] : [{ start: metadata[:insert_at], length: 0, text: callback }]
+      if metadata[:receiver]
+        receiver = metadata.fetch(:receiver)
+        edits << flow_replacement(bytes, receiver, nested, encloses) do |expression|
+          "#{runtime}.flow_iteration_begin(#{identifier}, (#{expression}), #{alternative_count})"
+        end
+      end
+      expression = flow_fragments(bytes, decision, nested, edits, encloses)
+      if metadata[:receiver]
+        "(begin; begin; #{runtime}.flow_iteration_finish(#{identifier}, (#{expression}), 0); ensure; " \
+          "#{runtime}.flow_iteration_leave(#{identifier}); end; end)"
+      else
+        flow_frame(decision[:id], expression, default_path: 0)
+      end
+    end
+  end
+end

data/lib/branchproof/iteration_runtime.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module Branchproof
+  # Runtime support for callback based iteration, including lazy receivers
+  # whose callbacks execute after the constructing call has returned.
+  module IterationRuntime
+    def flow_iteration_begin(decision_id, receiver, alternative_count = 2)
+      # Case equality bypasses an application's overridden `is_a?` method.
+      # rubocop:disable-next Style/CaseEquality
+      return receiver if alternative_count == 1 || ::Enumerator::Lazy === receiver
+
+      enter(decision_id)
+      receiver
+    end
+
+    # rubocop:disable-next Metrics/MethodLength
+    def flow_iteration_callback(decision_id, alternative_count = 2)
+      frame = iteration_frame(decision_id)
+      if frame
+        return nil if frame[:finished]
+
+        iteration_select(frame, alternative_count.to_i == 1 ? 0 : 1, alternative_count)
+      else
+        enter(decision_id)
+        begin
+          if alternative_count.to_i == 1
+            flow_select(decision_id, 0)
+          else
+            flow_path(decision_id, 1)
+          end
+        ensure
+          leave(decision_id)
+        end
+      end
+      nil
+    end
+
+    def flow_iteration_finish(decision_id, value, default_path = nil)
+      frame = iteration_frame(decision_id)
+      iteration_select(frame, default_path, 2) if frame && !frame[:finished] && !default_path.nil?
+      value
+    end
+
+    def flow_iteration_leave(decision_id)
+      frame = iteration_frame(decision_id)
+      frames = Thread.current[Branchproof::Runtime::FRAME_STATE_KEY]&.fetch(:frames, nil)
+      return nil unless frame && frames&.last.equal?(frame)
+
+      leave(decision_id)
+    end
+
+    private
+
+    # `current_frame` deliberately latches a diagnostic when a helper probes
+    # while another decision is active. Iteration callbacks may be deferred or
+    # nested, so an absent matching frame is an ordinary state here.
+    def iteration_frame(decision_id)
+      frames = Thread.current[Branchproof::Runtime::FRAME_STATE_KEY]&.fetch(:frames, nil)
+      index = frames ? frames.length - 1 : -1
+      while index >= 0
+        frame = frames[index]
+        return frame if frame[:decision_id] == decision_id
+
+        index -= 1
+      end
+      nil
+    end
+
+    def iteration_select(frame, index, alternative_count)
+      frame[:observations] = if alternative_count == 1
+                               [[0, true]]
+                             else
+                               [[0, index.zero?], [1, index == 1]]
+                             end
+      frame[:outcome] = true
+      frame[:finished] = true
+    end
+  end
+end

data/lib/branchproof/iteration_syntax.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module Branchproof
+  # Observe entry into source-visible callback bodies, not library internals.
+  module IterationSyntax
+    ITERATORS = %i[each each_with_index times upto downto step map collect select filter reject filter_map
+                   find detect find_index take_while drop_while partition count all? any? none? one? fetch].freeze
+
+    private
+
+    def flow_decision_node?(node)
+      iteration_node?(node) || node.is_a?(Prism::MatchRequiredNode) || super
+    end
+
+    def iteration_node?(node)
+      node.is_a?(Prism::ForNode) ||
+        (node.is_a?(Prism::CallNode) && ITERATORS.include?(node.name) &&
+         node.block.is_a?(Prism::BlockNode) && !node.safe_navigation?)
+    end
+
+    # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
+    def flow_details(node, bytes, encoding)
+      if node.is_a?(Prism::MatchRequiredNode)
+        alternatives = %w[matched mismatch].map { |label| iteration_alternative(node, label) }
+        return ["pattern", "required_pattern", alternatives,
+                { type: "required_pattern", range: byte_range(node.location) }, unsupported_reasons(node, bytes)]
+      end
+      return super unless iteration_node?(node)
+
+      body = node.is_a?(Prism::ForNode) ? node.statements : node.block.body
+      closing = node.is_a?(Prism::ForNode) ? node.end_keyword_loc : node.block.closing_loc
+      lazy = node.is_a?(Prism::CallNode) && lazy_receiver?(node.receiver)
+      fallback = node.is_a?(Prism::CallNode) && node.name == :fetch
+      context = if lazy
+                  "lazy_callback"
+                else
+                  (fallback ? "fetch_fallback" : "iteration")
+                end
+      labels = if lazy
+                 ["callback entered"]
+               else
+                 (fallback ? ["value present", "fallback entered"] : %w[empty entered])
+               end
+      metadata = { type: "iteration", range: byte_range(node.location), lazy: lazy,
+                   insert_at: iteration_insert_at(body, closing),
+                   empty: body.nil? }
+      metadata[:receiver] = byte_range(node.receiver.location) if node.is_a?(Prism::CallNode) && node.receiver
+      [lazy ? "multiway" : "implicit", context, labels.map { |label| iteration_alternative(node, label) },
+       metadata, unsupported_reasons(node, bytes)]
+    end
+
+    # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
+
+    def lazy_receiver?(node)
+      node.is_a?(Prism::CallNode) && (node.name == :lazy || lazy_receiver?(node.receiver))
+    end
+
+    # Prism gives a block-level rescue/ensure BeginNode a location beginning at
+    # the `do` keyword. Inserting there would produce `call; callback; do`, so
+    # anchor the callback after the block parameters and before its statements.
+    def iteration_insert_at(body, closing)
+      return closing.start_offset unless body
+
+      if body.is_a?(Prism::BeginNode)
+        statements = body.statements
+        return statements.location.start_offset if statements&.location
+      end
+      body.location.start_offset
+    end
+
+    def iteration_alternative(node, label)
+      { expression: label, byte_start: node.location.start_offset, byte_length: node.location.length }
+    end
+  end
+end

data/lib/branchproof/loader.rb

@@ -47,7 +47,12 @@ module Branchproof
         add_diagnostic("source_drift", "selected source changed after inventory", unit[:source_id])
         return nil
       end
-      rewritten = @instrumenter.rewrite(unit: unit.merge(original_bytes: bytes))
+      begin
+        rewritten = @instrumenter.rewrite(unit: unit.merge(original_bytes: bytes))
+      rescue StandardError => e
+        add_diagnostic("rewrite_failure", "#{e.class}: #{e.message}", unit[:source_id], severity: "error")
+        return nil
+      end
       Array(rewritten[:diagnostics]).each do |diagnostic|
         add_diagnostic(diagnostic[:code], diagnostic[:message], unit[:source_id], severity: diagnostic[:severity])
       end

data/lib/branchproof/project.rb

@@ -4,6 +4,7 @@ module Branchproof
   # Resolves the project policy used by the isolated analysis worker.
   class Project
     MODES = %w[auto ruby rails].freeze
+    FRAMEWORKS = %w[auto minitest rspec].freeze
     RAILS_ENVIRONMENT = {
       "RAILS_ENV" => "test",
       "RACK_ENV" => "test",
@@ -12,19 +13,24 @@ module Branchproof
       "DISABLE_SPRING" => "1"
     }.freeze
 
-    def initialize(root:, mode: "auto")
+    def initialize(root:, mode: "auto", framework: "auto")
       @root = File.expand_path(root)
       @mode = mode.to_s
+      @framework = framework.to_s
       raise ArgumentError, "project must be auto, ruby, or rails" unless MODES.include?(@mode)
+      raise ArgumentError, "framework must be auto, minitest, or rspec" unless FRAMEWORKS.include?(@framework)
 
       validate_root!
+      resolve_framework!
     end
 
     def to_h
       {
         kind: kind,
         root: @root,
-        load_paths: [File.join(@root, "lib"), File.join(@root, "test")],
+        framework: framework,
+        test_patterns: test_patterns,
+        load_paths: load_paths,
         environment: kind == "rails" ? RAILS_ENVIRONMENT.dup : {}
       }
     end
@@ -43,6 +49,47 @@ module Branchproof
         File.file?(File.join(@root, "config", "environment.rb"))
     end
 
+    def framework
+      @resolved_framework
+    end
+
+    def resolve_framework!
+      rspec = rspec_markers?
+      minitest = minitest_markers?
+      if @framework == "auto"
+        raise_both_frameworks if rspec && minitest
+        @resolved_framework = rspec ? "rspec" : "minitest"
+      else
+        @resolved_framework = @framework
+      end
+    end
+
+    def rspec_markers?
+      File.file?(File.join(@root, ".rspec")) || !Dir.glob(File.join(@root, "spec", "**", "*_spec.rb")).empty?
+    end
+
+    def raise_both_frameworks
+      raise ArgumentError,
+            "project contains both RSpec and Minitest markers; specify --framework rspec or --framework minitest"
+    end
+
+    def minitest_markers?
+      !Dir.glob(File.join(@root, "test", "**", "*_test.rb")).empty? ||
+        !Dir.glob(File.join(@root, "test", "**", "test_*.rb")).empty?
+    end
+
+    def test_patterns
+      if framework == "rspec"
+        %w[spec/**/*_spec.rb].freeze
+      else
+        %w[test/**/*_test.rb test/**/test_*.rb].freeze
+      end
+    end
+
+    def load_paths
+      [File.join(@root, "lib"), File.join(@root, framework == "rspec" ? "spec" : "test")]
+    end
+
     def validate_root!
       raise ArgumentError, "project root does not exist: #{@root}" unless File.directory?(@root)
       return unless @mode == "rails" && !rails_files?

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