branchproof 0.9.0 → 0.11.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

@@ -4,11 +4,13 @@
 
 require "json"
 require "pathname"
+require_relative "coverage_policy"
+require_relative "report_selection"
 
 module Branchproof
   # Renders versioned terminal and JSON analysis reports.
   class Report
-    SCHEMA_VERSION = "1.3"
+    SCHEMA_VERSION = "1.4"
     CRITERION_VERSION = "masking_occurrence_v1"
     VIEWS = %i[decisions conditions tests decision_tables].freeze
     DECISION_TABLE_LABELS = { "true" => "T", "false" => "F", "dont_care" => "-" }.freeze
@@ -16,7 +18,7 @@ module Branchproof
                                      "excluded" => "EXCLUDED" }.freeze
 
     def initialize(inventory:, evidence:, analysis:, minima:, baseline:, diagnostics:, level: 3, missing_only: false,
-                   view: :decisions, run_metadata: {}, saved_document: nil)
+                   view: :decisions, run_metadata: {}, saved_document: nil, focus: nil, top: nil, minimum: nil)
       raise ArgumentError, "level must be 1, 2, or 3" unless [1, 2, 3].include?(level.to_i)
       unless VIEWS.include?(view.to_sym)
         raise ArgumentError, "view must be :decisions, :conditions, :tests, or :decision_tables"
@@ -33,21 +35,29 @@ module Branchproof
       @view = view.to_sym
       @run_metadata = run_metadata || {}
       @saved_document = saved_document
+      raise ArgumentError, "minimum must be a hash" if !minimum.nil? && !minimum.is_a?(Hash)
+
+      @minimum_override = minimum.is_a?(Hash) && !minimum.empty? ? CoveragePolicy.normalize(minimum) : nil
+      @minimum = effective_minimum
+      @selection = ReportSelection.new(focus: focus, top: top)
     end
 
-    def self.from_document(document:, level: nil, view: :decisions, missing_only: false)
+    def self.from_document(document:, level: nil, view: :decisions, missing_only: false, focus: nil, top: nil,
+                           minimum: nil)
       data = document || {}
       new(inventory: data[:source_inventory] || data["source_inventory"],
           evidence: data[:observations] || data["observations"],
           analysis: data[:analysis] || data["analysis"], minima: data[:minima] || data["minima"],
           baseline: data[:baseline] || data["baseline"], diagnostics: data[:diagnostics] || data["diagnostics"],
           level: level || (data[:analysis] || data["analysis"] ? 3 : 1), view: view, missing_only: missing_only,
-          run_metadata: data[:run_metadata] || data["run_metadata"], saved_document: data)
+          focus: focus, top: top,
+          run_metadata: data[:run_metadata] || data["run_metadata"], saved_document: data, minimum: minimum)
     end
 
     def write(io:, format:)
       format = format.to_sym
       raise ArgumentError, "format must be :terminal or :json" unless %i[terminal json].include?(format)
+      raise ArgumentError, "focus and top filters are terminal-only" if format == :json && @selection.active?
 
       io.write(format == :json ? JSON.generate(json_document) : terminal_document)
       nil
@@ -105,6 +115,10 @@ module Branchproof
     def exit_code
       return 2 unless usage_valid?
 
+      policy_status = value(coverage_policy, :status).to_s
+      return 2 if policy_status == "unavailable"
+      return 1 if policy_status == "failed"
+
       status = value(@baseline, :status).to_s.upcase
       return 2 if %w[ERROR INCOMPLETE].include?(status)
       return 1 if status == "FAILED"
@@ -118,10 +132,24 @@ 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
-      return normalize(@saved_document) if @saved_document
+      if @saved_document
+        document = normalize(@saved_document)
+        document["coverage_policy"] = normalize(coverage_policy) if @minimum_override
+        return document
+      end
 
       normalize(schema_version: SCHEMA_VERSION,
                 tool_version: (defined?(Branchproof::VERSION) ? Branchproof::VERSION : "unknown"),
@@ -129,14 +157,15 @@ module Branchproof
                 run_ids: Array(value(@evidence, :run_ids)),
                 source_inventory: inventory_with_default_kinds, baseline: @baseline, observations: @evidence,
                 analysis: @analysis, minima: @minima, metrics: metrics,
-                diagnostics: @diagnostics, completeness: completeness,
+                diagnostics: @diagnostics, completeness: completeness, coverage_policy: coverage_policy,
                 run_metadata: @run_metadata)
     end
 
     def terminal_document
       unless @view == :decisions
         return FocusedReport.new(document: json_document, view: @view, level: @level,
-                                 missing_only: @missing_only, coordinator: self).render
+                                 missing_only: @missing_only, coordinator: self,
+                                 selection: @selection).render
       end
 
       @terminal_ids = terminal_ids
@@ -151,10 +180,13 @@ module Branchproof
                "#{metrics[:unattributed]} unattributed",
                values_legend]
       lines.concat(coverage_ladder_lines)
+      lines.concat(coverage_policy_lines)
       lines << missing_summary_line if @missing_only
+      selected_decisions, hidden = selected_decisions_for_display
+      append_selection_lines(lines, hidden, "decision")
       lines << "Scope: supported decisions, conditions, and alternatives"
       lines << ""
-      decisions_to_render.each { |decision| render_decision(lines, decision) }
+      selected_decisions.each { |decision| render_decision(lines, decision) }
       render_minima(lines) unless @missing_only
       unless @diagnostics.empty?
         lines << "Diagnostics:"
@@ -507,10 +539,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 +623,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
 
@@ -910,6 +952,33 @@ module Branchproof
         end
     end
 
+    def selected_decisions_for_display
+      decisions = decisions_to_render
+      return [decisions, 0] unless @selection.active?
+
+      inventory = value(@inventory, :source_units) ? @inventory : { source_units: [], decisions: inventory_decisions }
+      decisions = @selection.filter_decisions(decisions, inventory: inventory)
+      decisions = decisions.sort_by { |decision| @selection.sort_key(decision, inventory: inventory) }
+      @selection.limit(decisions)
+    end
+
+    def append_selection_lines(lines, hidden, unit)
+      if @selection.focus_active?
+        matching = @selection.matching_decision_ids(json_document)
+        lines << if matching.empty?
+                   "Focus: no matching decisions for #{@selection.focus_label}"
+                 else
+                   "Focus: #{@selection.focus_label}"
+                 end
+      end
+      return unless @selection.top
+
+      noun = hidden == 1 ? unit : "#{unit}s"
+      hidden_noun = hidden == 1 ? unit : "#{unit}s"
+      lines << "Display limit: top #{@selection.top} #{noun}; hidden #{hidden} #{hidden_noun} " \
+               "(not risk-ranked)"
+    end
+
     def alternatives_to_render(decision)
       alternatives = Array(value(decision, :alternatives))
       return alternatives unless @missing_only && analysis_available?
@@ -942,6 +1011,44 @@ module Branchproof
       !@analysis.nil?
     end
 
+    def coverage_policy
+      @coverage_policy ||= CoveragePolicy.new(minimum: @minimum).call(document: policy_document)
+    end
+
+    def coverage_policy_lines
+      policy = coverage_policy
+      minimum = value(policy, :minimum) || {}
+      return [] if minimum.empty?
+
+      lines = ["Coverage policy: #{value(policy, :status).to_s.upcase}"]
+      Array(value(policy, :gates)).each do |gate|
+        numerator = value(gate, :numerator)
+        denominator = value(gate, :denominator)
+        count = if denominator.nil? || (denominator.respond_to?(:zero?) && denominator.zero?)
+                  "N/A"
+                else
+                  "#{numerator || "N/A"}/#{denominator}"
+                end
+        suffix = value(gate, :reason) ? "; reason: #{value(gate, :reason)}" : ""
+        lines << "  #{value(gate, :criterion)}: #{count}, threshold #{value(gate, :minimum)}, " \
+                 "#{value(gate, :status).to_s.upcase}#{suffix}"
+      end
+      lines << ""
+      lines
+    end
+
+    def policy_document
+      { baseline: @baseline, completeness: value(@saved_document, :completeness) || completeness,
+        observations: value(@saved_document, :observations) || @evidence,
+        analysis: value(@saved_document, :analysis) || @analysis }
+    end
+
+    def effective_minimum
+      inherited = value(value(@saved_document, :coverage_policy), :minimum)
+      base = inherited.is_a?(Hash) ? CoveragePolicy.normalize(inherited) : {}
+      base.merge(@minimum_override || {})
+    end
+
     def coverage_available?
       analysis_available? && !value(@analysis, :coverage).nil?
     end
@@ -1150,7 +1257,8 @@ module Branchproof
     def normalize_unknown(object)
       object.to_s
     end
-    public :condition_coverage_evidence, :coverage_ladder_lines, :coverage_status_label,
+    public :condition_coverage_evidence, :coverage_ladder_lines, :coverage_policy_lines, :coverage_policy,
+           :coverage_status_label,
            :decision_table_requirement, :decision_table_reachability, :decision_table_expected_heading
   end
 end

data/lib/branchproof/report_selection.rb

@@ -0,0 +1,158 @@
+# frozen_string_literal: true
+
+require "pathname"
+
+module Branchproof
+  # Validates and applies terminal-only report display filters.
+  # rubocop:disable Metrics/ClassLength, Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
+  class ReportSelection
+    attr_reader :focus, :top
+
+    def initialize(focus: nil, top: nil)
+      @focus = normalize_focus(focus)
+      @top = normalize_top(top)
+    end
+
+    def active?
+      !@focus.nil? || !@top.nil?
+    end
+
+    def focus_active?
+      !@focus.nil?
+    end
+
+    def focus_label
+      return unless @focus
+
+      @focus[:line] ? "#{@focus[:path]}:#{@focus[:line]}" : @focus[:path]
+    end
+
+    def matching_decision_ids(document)
+      inventory = fetch(document, :source_inventory) || fetch(document, :inventory) || {}
+      sources = source_map(inventory)
+      Array(fetch(inventory, :decisions)).filter_map do |decision|
+        next unless matches_decision?(decision, sources)
+
+        fetch(decision, :id).to_s
+      end
+    end
+
+    def filter_decisions(decisions, inventory: {})
+      return decisions unless focus_active?
+
+      sources = source_map(inventory)
+      decisions.select { |decision| matches_decision?(decision, sources) }
+    end
+
+    def limit(items)
+      return [items, 0] unless @top
+
+      [items.first(@top), [items.length - @top, 0].max]
+    end
+
+    def sort_key(decision, inventory: {})
+      source = source_for(decision, source_map(inventory))
+      [normalize_source_path(fetch(source, :relative_path)).to_s,
+       fetch(decision, :line).to_i, fetch(decision, :column).to_i, fetch(decision, :id).to_s]
+    end
+
+    private
+
+    def normalize_focus(focus)
+      return nil if focus.nil?
+      raise ArgumentError, "focus must be PATH or PATH:LINE" unless focus.is_a?(String)
+
+      raw = focus.strip
+      raise ArgumentError, "focus path must not be empty" if raw.empty?
+
+      path, line = if raw.match?(/:\d+\z/)
+                     match = raw.match(/\A(.+):([0-9]+)\z/)
+                     raise ArgumentError, "focus path must not be empty" unless match
+
+                     [match[1], match[2].to_i]
+                   else
+                     raise ArgumentError, "focus line must be a positive integer" if raw.include?(":")
+
+                     [raw, nil]
+                   end
+      raise ArgumentError, "focus line must be a positive integer" if line && line <= 0
+
+      { path: normalize_path(path), line: line }.freeze
+    end
+
+    def normalize_top(top)
+      return nil if top.nil?
+
+      value = if top.is_a?(Integer)
+                top
+              elsif top.is_a?(String) && top.match?(/\A[1-9][0-9]*\z/)
+                top.to_i
+              end
+      raise ArgumentError, "top must be a positive integer" unless value&.positive?
+
+      value
+    end
+
+    def normalize_path(path)
+      text = path.to_s
+      raise ArgumentError, "focus path must not be empty" if text.empty? || text.include?("\0")
+
+      pathname = Pathname.new(text)
+      raise ArgumentError, "focus path must be project-relative" if pathname.absolute?
+
+      normalized = pathname.cleanpath.to_s
+      if normalized == "." || normalized == ".." || normalized.start_with?("../")
+        raise ArgumentError, "focus path must stay within the project"
+      end
+
+      normalized
+    rescue ArgumentError
+      raise
+    rescue StandardError => e
+      raise ArgumentError, "invalid focus path: #{e.message}"
+    end
+
+    def matches_decision?(decision, sources)
+      return false unless @focus
+
+      source = source_for(decision, sources)
+      return false unless normalize_source_path(fetch(source, :relative_path)) == @focus[:path]
+      return true unless @focus[:line]
+
+      start_line = fetch(decision, :line).to_i
+      return false unless start_line.positive?
+
+      end_line = start_line + fetch(decision, :expression).to_s.count("\n")
+      @focus[:line].between?(start_line, end_line)
+    end
+
+    def source_for(decision, sources)
+      sources[fetch(decision, :source_id).to_s] || decision
+    end
+
+    def source_map(inventory)
+      Array(fetch(inventory, :source_units)).to_h do |source|
+        [fetch(source, :source_id).to_s, source]
+      end
+    end
+
+    def normalize_source_path(path)
+      return nil if path.nil? || path.to_s.empty?
+      return nil if Pathname.new(path.to_s).absolute?
+
+      Pathname.new(path.to_s).cleanpath.to_s
+    rescue ArgumentError
+      nil
+    end
+
+    def fetch(hash, key)
+      return nil unless hash.respond_to?(:key?)
+      return hash[key] if hash.key?(key)
+      return hash[key.to_s] if hash.key?(key.to_s)
+
+      nil
+    end
+  end
+end
+
+# rubocop:enable Metrics/ClassLength, Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity