branchproof 0.2.0

data/lib/branchproof/loader.rb

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+
+require "digest"
+
+module Branchproof
+  # Owns the process-local CRuby compilation hook when the VM exposes it.
+  class Loader
+    STATUS_KEYS = %i[status reason].freeze
+
+    def initialize(inventory:, instrumenter:)
+      @inventory = inventory
+      @instrumenter = instrumenter
+      @diagnostics = []
+      @installed = false
+      @units = index_units(inventory)
+      @hook_source_location = nil
+    end
+
+    def install
+      return status(:rejected, :preloaded_target) if preloaded_target?
+
+      unless hook_supported?
+        add_diagnostic("unsupported_runtime", "RubyVM::InstructionSequence cannot install a load_iseq hook")
+        return status(:rejected, :unsupported_runtime)
+      end
+      if competing_owner?
+        add_diagnostic("loader_conflict", "another load_iseq owner is already installed")
+        return status(:rejected, :loader_conflict)
+      end
+
+      @installed = true
+      owner = self
+      RubyVM::InstructionSequence.define_singleton_method(:load_iseq) do |path|
+        owner.load_iseq(path)
+      end
+      RubyVM::InstructionSequence.instance_variable_set(:@branchproof_load_iseq_owner, self)
+      @hook_source_location = RubyVM::InstructionSequence.method(:load_iseq).source_location
+      status(:installed, nil)
+    end
+
+    def load_iseq(path)
+      return nil unless @installed
+
+      unit = @units[canonical(path)]
+      return nil unless unit
+
+      bytes = File.binread(path)
+      if digest_for(bytes) != expected_digest(unit)
+        add_diagnostic("source_drift", "selected source changed after inventory", unit[:source_id])
+        return nil
+      end
+      rewritten = @instrumenter.rewrite(unit: unit.merge(original_bytes: bytes))
+      Array(rewritten[:diagnostics]).each do |diagnostic|
+        add_diagnostic(diagnostic[:code], diagnostic[:message], unit[:source_id], severity: diagnostic[:severity])
+      end
+      unless rewritten[:changed]
+        if Array(rewritten[:diagnostics]).empty?
+          add_diagnostic("not_instrumented", "selected source had no safe edits", unit[:source_id],
+                         severity: "info")
+        end
+        return nil
+      end
+
+      RubyVM::InstructionSequence.compile(
+        rewritten[:bytes], unit[:real_path] || canonical(path), unit[:real_path] || canonical(path), 1,
+        compile_options(unit)
+      )
+    rescue Errno::ENOENT => e
+      add_diagnostic("load_error", e.message, unit && unit[:source_id])
+      nil
+    end
+
+    def diagnostics
+      if @installed && !hook_owned?
+        add_diagnostic("loader_conflict", "load_iseq hook ownership changed after installation")
+        @installed = false
+      end
+      @diagnostics.dup.freeze
+    end
+
+    private
+
+    def hook_supported?
+      defined?(RubyVM::InstructionSequence) && RubyVM::InstructionSequence.respond_to?(:compile)
+    end
+
+    def competing_owner?
+      return false unless RubyVM::InstructionSequence.respond_to?(:load_iseq)
+
+      owner = RubyVM::InstructionSequence.instance_variable_get(:@branchproof_load_iseq_owner)
+      return false if owner.equal?(self) && hook_owned?
+
+      true
+    end
+
+    def hook_owned?
+      RubyVM::InstructionSequence.respond_to?(:load_iseq) &&
+        RubyVM::InstructionSequence.instance_variable_get(:@branchproof_load_iseq_owner).equal?(self) &&
+        RubyVM::InstructionSequence.method(:load_iseq).source_location == @hook_source_location
+    end
+
+    def preloaded_target?
+      @units.keys.any? { |path| $LOADED_FEATURES.any? { |feature| canonical(feature) == path } }
+    end
+
+    def index_units(inventory)
+      Array(inventory[:source_units]).each_with_object({}) do |unit, index|
+        path = unit[:absolute_path] || unit[:real_path]
+        index[canonical(path)] = unit if path
+      end
+    end
+
+    def canonical(path)
+      File.realpath(path.to_s)
+    rescue Errno::ENOENT
+      File.expand_path(path.to_s)
+    end
+
+    def expected_digest(unit)
+      unit[:digest] || digest_for(unit[:original_bytes].to_s)
+    end
+
+    def digest_for(bytes)
+      Digest::SHA256.hexdigest(bytes)
+    end
+
+    def compile_options(unit)
+      unit[:compile_options] || {}
+    end
+
+    def status(state, reason)
+      { status: state.to_s, reason: reason&.to_s }.freeze
+    end
+
+    def add_diagnostic(code, message, source_id = nil, severity: "error")
+      @diagnostics << { code: code.to_s, severity: severity.to_s, message: message, source_id: source_id,
+                        decision_id: nil, execution_id: nil, test_id: nil, details: {} }.freeze
+    end
+  end
+end

data/lib/branchproof/minimizer.rb

@@ -0,0 +1,198 @@
+# frozen_string_literal: true
+
+# rubocop:disable-next Lint/RedundantRequireStatement -- supports standalone core entry
+require "set"
+
+module Branchproof
+  # Computes minimum vector or test covers for proven obligations.
+  class Minimizer
+    def initialize(analysis:, evidence:, limits:)
+      @analysis = analysis || {}
+      @evidence = evidence || {}
+      @limits = limits || {}
+    end
+
+    def call(objective:, decision_ids:)
+      raise ArgumentError, "objective must be :vectors or :tests" unless %i[vectors tests].include?(objective)
+
+      scope = Array(decision_ids).map(&:to_s).sort
+      if objective == :vectors && scope.length != 1
+        raise ArgumentError,
+              "vector objective requires exactly one decision"
+      end
+
+      target = target_obligations(scope)
+      return result(objective, scope, target, [], "EXACT_MINIMUM", nil, 0, []) if target.empty?
+
+      candidates = objective == :tests ? test_candidates(scope) : vector_candidates(scope)
+      candidates = candidates.transform_values { |signs| signs & target }
+      union = candidates.values.reduce(Set.new) { |set, signs| set | signs }
+      missing = target - union
+      unless missing.empty?
+        return result(objective, scope, target, [], "NOT_AVAILABLE", nil, 0,
+                      ["missing ownership: #{format_obligations(missing)}"])
+      end
+
+      candidate_cap = integer_limit(:exact_candidates, 32)
+      exact_candidate_set = candidates.keys.length <= candidate_cap
+      unless exact_candidate_set
+        selected = greedy(candidates.keys.sort, candidates, target)
+        covered = selected.reduce(Set.new) { |set, candidate| set | candidates.fetch(candidate, Set.new) }
+        status = covered >= target ? "BEST_FOUND" : "NOT_AVAILABLE"
+        reasons = if status == "BEST_FOUND"
+                    ["candidate count exceeds exact search limit"]
+                  else
+                    ["candidate union is incomplete"]
+                  end
+        return result(objective, scope, target, selected, status, nil, 0, reasons, candidates)
+      end
+      selected, exact, lower, visited = search(candidates, target)
+      exact &&= exact_candidate_set
+      covered = selected.reduce(Set.new) { |set, candidate| set | candidates.fetch(candidate, Set.new) }
+      status = exact && covered >= target ? "EXACT_MINIMUM" : "BEST_FOUND"
+      result(objective, scope, target, selected, status, lower, visited,
+             status == "EXACT_MINIMUM" ? [] : ["exact search budget exhausted"], candidates)
+    end
+
+    private
+
+    def target_obligations(scope)
+      records(@analysis, :decisions).select { scope.include?(id(_1, :decision_id).to_s) }.flat_map do |decision|
+        records(decision, :condition_results).filter_map do |condition|
+          next unless id(condition, :status).to_s == "PROVEN"
+
+          condition_id = id(condition, :condition_id).to_s
+          index = records(decision, :conditions).find { id(_1, :id).to_s == condition_id }
+          idx = index && id(index, :index)
+          [true, false].map { |sign| [id(decision, :decision_id).to_s, idx, sign] }
+        end
+      end.flatten(1).to_set
+    end
+
+    def vector_candidates(scope)
+      selected_decisions = records(@analysis, :decisions).select do |decision|
+        scope.include?(id(decision, :decision_id).to_s)
+      end
+      masks = selected_decisions.to_h do |decision|
+        [id(decision, :decision_id).to_s, id(decision, :effective_masks_by_vector) || {}]
+      end
+      records(@evidence, :vectors).each_with_object({}) do |vector, result|
+        decision_id = id(vector, :decision_id).to_s
+        next unless masks.key?(decision_id)
+
+        mask = masks[decision_id][id(vector, :id)] || masks[decision_id][id(vector, :id).to_s]
+        next unless mask
+
+        indexes = mask.to_i.digits(2).each_index.select { |index| mask.to_i[index] == 1 }
+        signs = indexes.flat_map do |index|
+          [[decision_id, index, true], [decision_id, index, false]].select do |obligation|
+            value(vector, index) == obligation[2]
+          end
+        end.to_set
+        result[id(vector, :id).to_s] = signs
+      end
+    end
+
+    def test_candidates(scope)
+      vectors = vector_candidates(scope)
+      result = Hash.new { |hash, key| hash[key] = Set.new }
+      records(@evidence, :vectors).each do |vector|
+        test_ids = records(vector, :test_ids)
+        next if test_ids.empty?
+
+        signs = vectors[id(vector, :id).to_s]
+        next unless signs
+
+        test_ids.each { |test_id| result[test_id.to_s] |= signs }
+      end
+      result
+    end
+
+    def search(candidates, target)
+      ids = candidates.keys.sort
+      best = greedy(ids, candidates, target)
+      nodes = 0
+      limit = integer_limit(:exact_search_nodes, 100_000)
+      exact = true
+      visit = lambda do |position, chosen, covered|
+        if nodes >= limit
+          exact = false
+          return
+        end
+        nodes += 1
+        if covered >= target
+          candidate = chosen.sort
+          if candidate.length < best.length || (candidate.length == best.length && (candidate <=> best) == -1)
+            best = candidate
+          end
+          return
+        end
+        return if position >= ids.length || chosen.length >= best.length
+
+        gain = candidates[ids[position]] - covered
+        visit.call(position + 1, chosen, covered)
+        visit.call(position + 1, chosen + [ids[position]], covered | gain) unless gain.empty?
+      end
+      visit.call(0, [], Set.new)
+      greatest_gain = candidates.values.map(&:length).max.to_i
+      lower_bound = greatest_gain.zero? ? nil : ((target.length + greatest_gain - 1) / greatest_gain)
+      [best, exact, lower_bound, nodes]
+    end
+
+    def greedy(ids, candidates, target)
+      chosen = []
+      covered = Set.new
+      until covered >= target
+        available = ids.reject { |candidate| chosen.include?(candidate) }
+        id = available.max_by { |candidate| [(candidates[candidate] - covered).length, -ids.index(candidate)] }
+        break unless id
+        break if (candidates[id] - covered).empty?
+
+        chosen << id
+        covered |= candidates[id]
+      end
+      chosen.sort.reverse_each do |candidate|
+        trial = chosen - [candidate]
+        trial_covered = trial.reduce(Set.new) { |set, item| set | candidates[item] }
+        chosen = trial if trial_covered >= target
+      end
+      chosen.sort
+    end
+
+    def result(objective, scope, target, selected, status, lower, visited, reasons, candidates = {})
+      necessary = candidates.keys.reject do |candidate|
+        others = candidates.reject { |key, _| key == candidate }.values.reduce(Set.new, :|)
+        covers?(others, target)
+      end
+      interchangeable = candidates.keys.select do |candidate|
+        candidates.fetch(candidate).intersect?(target) && candidates.reject do |key, _|
+          key == candidate
+        end.values.reduce(Set.new, :|) >= target
+      end
+      { objective: objective, scope_decision_ids: scope,
+        target_obligations: target.to_a.sort_by do |decision, index, sign|
+          [decision.to_s, index.to_i, sign ? 1 : 0]
+        end, selected_ids: selected,
+        status: status, lower_bound: lower, visited_nodes: visited, reasons: reasons,
+        necessary_ids: necessary, interchangeable_ids: interchangeable,
+        additional_ids: candidates.keys.sort - selected }
+    end
+
+    def format_obligations(obligations)
+      obligations.to_a.sort_by do |decision, index, sign|
+        [decision.to_s, index.to_i, sign ? 1 : 0]
+      end.map(&:inspect).join(", ")
+    end
+
+    def integer_limit(key, default)
+      value = id(@limits, key)
+      value&.to_i&.positive? ? value.to_i : default
+    end
+
+    def covers?(set, target) = set >= target
+
+    def value(vector, index) = (vector[:values] || vector["values"])[index]
+    def id(record, key) = record[key].nil? ? record[key.to_s] : record[key]
+    def records(record, key) = Array(id(record, key))
+  end
+end

data/lib/branchproof/minitest_adapter.rb

@@ -0,0 +1,245 @@
+# frozen_string_literal: true
+
+module Branchproof
+  # Bridges one serial Minitest run to Runtime lifecycle ownership.
+  class MinitestAdapter
+    class << self
+      attr_accessor :active_adapter
+    end
+
+    def initialize(runtime:)
+      @runtime = runtime
+      @registered = false
+      @tests = {}
+    end
+
+    def capabilities
+      { serial: true, phases: true }.freeze
+    end
+
+    def run(test_files:, runner_args:, on_complete:, before_load: nil)
+      raise ArgumentError, "test_files must be an Array" unless test_files.is_a?(Array)
+      raise ArgumentError, "on_complete must respond to call" unless on_complete.respond_to?(:call)
+
+      reject_runner_args!(runner_args)
+      @runner_args = Array(runner_args).dup.freeze
+      require "minitest"
+      require "minitest/test"
+      self.class.active_adapter = self
+      install_lifecycle_hooks
+      install_runner_guard
+      Minitest.after_run do
+        on_complete.call(baseline_result)
+      rescue StandardError => e
+        @completion_error = e
+      ensure
+        self.class.active_adapter = nil
+      end
+      @loading_test_files = true
+      before_load&.call
+      test_files.each { |path| require path }
+      @registered = true
+      nil
+    ensure
+      @loading_test_files = false
+    end
+
+    attr_reader :tests
+
+    def validate_runner!
+      runnables = defined?(Minitest::Runnable) ? Minitest::Runnable.runnables : []
+      parallel = parallel_executor_active? || runnables.any? { |runnable| parallel_runnable?(runnable) }
+      raise ArgumentError, "parallel test scheduling is unsupported" if parallel
+
+      nil
+    end
+
+    private
+
+    def install_lifecycle_hooks
+      return if self.class.instance_variable_defined?(:@hooks_installed)
+
+      Minitest::Test.prepend(Module.new do
+        define_method(:run) do |*args, &block|
+          adapter = Branchproof::MinitestAdapter.active_adapter
+          return super(*args, &block) unless adapter
+
+          begin
+            adapter.send(:begin_test, self)
+            adapter.send(:install_phase_hooks, self.class)
+            super(*args, &block)
+          ensure
+            adapter.send(:end_test, self)
+          end
+        end
+      end)
+      self.class.instance_variable_set(:@hooks_installed, true)
+    end
+
+    def install_runner_guard
+      return if Minitest.singleton_class.instance_variable_defined?(:@branchproof_runner_guard)
+
+      Minitest.singleton_class.prepend(Module.new do
+        define_method(:run) do |*args, &block|
+          adapter = Branchproof::MinitestAdapter.active_adapter
+          return super(*args, &block) unless adapter
+
+          if adapter.instance_variable_get(:@loading_test_files)
+            raise ArgumentError, "custom Minitest runners are unsupported"
+          end
+          if adapter.instance_variable_get(:@branchproof_native_run)
+            raise ArgumentError, "Minitest runner invoked more than once"
+          end
+
+          adapter.instance_variable_set(:@branchproof_native_run, true)
+          super(*args, &block)
+        end
+      end)
+      Minitest.singleton_class.instance_variable_set(:@branchproof_runner_guard, true)
+    end
+
+    def parallel_executor_active?
+      return false unless Minitest.respond_to?(:parallel_executor)
+
+      executor = Minitest.parallel_executor
+      return false unless executor
+
+      rails_executor = defined?(ActiveSupport::Testing::ParallelizeExecutor) &&
+                       executor.is_a?(ActiveSupport::Testing::ParallelizeExecutor)
+      return false unless rails_executor
+
+      size = executor.respond_to?(:size) ? executor.size : nil
+      size.nil? || size.to_i > 1
+    end
+
+    def parallel_runnable?(runnable)
+      parallel_module = defined?(Minitest::Parallel::Test) && Minitest::Parallel::Test
+      return true if parallel_module && runnable.ancestors.include?(parallel_module)
+
+      runnable.respond_to?(:test_order) && runnable.test_order == :parallel
+    end
+
+    def begin_test(test)
+      test_id = test_id_for(test)
+      source = begin
+        test.method(test.name).source_location
+      rescue StandardError
+        nil
+      end
+      @tests[test_id] = { id: test_id, adapter: "minitest", name: test.name,
+                          source: source && { path: source[0], line: source[1] }, class_name: test.class.name,
+                          method_name: test.name, status: "running", phase_counts: {} }
+      register_test(@tests[test_id])
+      context(test_id, "setup")
+    end
+
+    def install_phase_hooks(test_class)
+      return if test_class.instance_variable_defined?(:@branchproof_phase_hooks)
+
+      adapter = self
+      test_class.prepend(Module.new do
+        define_method(:after_setup) do |*args, &block|
+          result = super(*args, &block)
+          adapter.send(:context, adapter.send(:test_id_for, self), "body")
+          result
+        end
+
+        define_method(:before_teardown) do |*args, &block|
+          adapter.send(:context, adapter.send(:test_id_for, self), "teardown")
+          super(*args, &block)
+        end
+      end)
+      test_class.instance_variable_set(:@branchproof_phase_hooks, true)
+    end
+
+    def end_test(test)
+      test_id = test_id_for(test)
+      context(nil, "unattributed")
+      record = @tests[test_id]
+      return unless record
+
+      skipped = test.failures.any? do |failure|
+        (failure.respond_to?(:skipped?) && failure.skipped?) ||
+          (defined?(Minitest::Skip) && failure.respond_to?(:error) && failure.error.is_a?(Minitest::Skip)) ||
+          failure.class.name.to_s.include?("Skip")
+      end
+      record[:status] = if skipped
+                          "skipped"
+                        else
+                          (test.failures.empty? ? "passed" : "failed")
+                        end
+      register_test(record)
+    end
+
+    def context(test_id, phase)
+      if test_id && @tests[test_id]
+        counts = @tests[test_id][:phase_counts]
+        counts[phase] = counts.fetch(phase, 0) + 1
+      end
+      return unless @runtime.respond_to?(:context)
+
+      @runtime.context(test_id: test_id, phase: phase)
+    end
+
+    def test_id_for(test)
+      source = begin
+        test.method(test.name).source_location
+      rescue NameError
+        nil
+      end
+      if defined?(Branchproof::Records)
+        Branchproof::Records.id(adapter: "minitest", class_name: test.class.name, method_name: test.name,
+                                source: source)
+      else
+        "minitest:#{test.class}:#{test.name}:#{source}"
+      end
+    end
+
+    def register_test(test)
+      if @runtime.respond_to?(:register_test)
+        @runtime.register_test(test: test)
+      else
+        evidence = @runtime.instance_variable_get(:@evidence)
+        evidence.register_test(test: test) if evidence.respond_to?(:register_test)
+      end
+    end
+
+    def baseline_result
+      if @completion_error
+        return { status: "ERROR", executed_tests: @tests.length, failed_tests: 0, skipped_tests: 0,
+                 exit_status: 2, finalized: false,
+                 diagnostics: [{ code: "completion_callback", severity: "error", message: @completion_error.message }] }
+      end
+      tests = @tests.values
+      failed = tests.count { |test| test[:status] == "failed" }
+      skipped = tests.count { |test| test[:status] == "skipped" }
+      {
+        status: if tests.empty?
+                  "INCOMPLETE"
+                else
+                  (failed.zero? ? "PASSED" : "FAILED")
+                end,
+        executed_tests: tests.length, failed_tests: failed, skipped_tests: skipped,
+        seed: seed_value, exit_status: failed.zero? ? 0 : 1,
+        finalized: true, tests: tests
+      }
+    end
+
+    def seed_value
+      index = @runner_args.index("--seed")
+      if index && @runner_args[index + 1]
+        @runner_args[index + 1].to_i
+      else
+        (Minitest.respond_to?(:seed) ? Minitest.seed : nil)
+      end
+    end
+
+    def reject_runner_args!(args)
+      forbidden = Array(args).select do |arg|
+        %w[--parallel --parallelize --fork --processes
+           --runner].include?(arg.to_s) || arg.to_s.start_with?("--parallel=", "--fork=", "--processes=")
+      end
+      raise ArgumentError, "parallel, forked, and custom runners are unsupported" unless forbidden.empty?
+    end
+  end
+end

data/lib/branchproof/project.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Branchproof
+  # Resolves the project policy used by the isolated analysis worker.
+  class Project
+    MODES = %w[auto ruby rails].freeze
+    RAILS_ENVIRONMENT = {
+      "RAILS_ENV" => "test",
+      "RACK_ENV" => "test",
+      "PARALLEL_WORKERS" => "1",
+      "DISABLE_BOOTSNAP" => "1",
+      "DISABLE_SPRING" => "1"
+    }.freeze
+
+    def initialize(root:, mode: "auto")
+      @root = File.expand_path(root)
+      @mode = mode.to_s
+      raise ArgumentError, "project must be auto, ruby, or rails" unless MODES.include?(@mode)
+
+      validate_root!
+    end
+
+    def to_h
+      {
+        kind: kind,
+        root: @root,
+        load_paths: [File.join(@root, "lib"), File.join(@root, "test")],
+        environment: kind == "rails" ? RAILS_ENVIRONMENT.dup : {}
+      }
+    end
+
+    private
+
+    def kind
+      return "rails" if @mode == "rails"
+      return "ruby" if @mode == "ruby"
+
+      rails_files? ? "rails" : "ruby"
+    end
+
+    def rails_files?
+      File.file?(File.join(@root, "config", "application.rb")) &&
+        File.file?(File.join(@root, "config", "environment.rb"))
+    end
+
+    def validate_root!
+      raise ArgumentError, "project root does not exist: #{@root}" unless File.directory?(@root)
+      return unless @mode == "rails" && !rails_files?
+
+      raise ArgumentError, "Rails project requires config/application.rb and config/environment.rb"
+    end
+  end
+end