branchproof 0.6.0 → 0.8.0

data/lib/branchproof/constraints.rb

@@ -0,0 +1,363 @@
+# frozen_string_literal: true
+
+require "prism"
+
+module Branchproof
+  # Normalizes simple atomic conditions into subject/operator/value records and
+  # decides, conservatively, whether a set of required condition truths can hold
+  # at the same time.
+  #
+  # The module never evaluates application code. It only inspects the syntax of
+  # a condition, and it answers "contradictory" only when the contradiction
+  # follows from the normalized constraints alone. Every other shape stays
+  # unrepresented, which leaves the owning decision-table rule reachability
+  # +unknown+.
+  module Constraints
+    VERSION = 2
+
+    NUMERIC_OPERATORS = %w[< <= > >=].freeze
+    COMPARISON_OPERATORS = %w[< <= > >= == !=].freeze
+    OPERATORS = (COMPARISON_OPERATORS + ["truthy"]).freeze
+    FLIPPED = { "<" => ">", "<=" => ">=", ">" => "<", ">=" => "<=", "==" => "==", "!=" => "!=" }.freeze
+    NUMERIC_TYPES = %w[integer float].freeze
+    FALSEY_TYPES = %w[nil false].freeze
+    LITERAL_TYPES = %w[integer float symbol nil true false].freeze
+    SUBJECT_KINDS = %w[local instance class global constant].freeze
+    REASONS = %w[
+      conflicting_numeric_bounds conflicting_equalities equality_outside_numeric_range
+      nil_conflict boolean_literal_conflict
+    ].freeze
+    REASON_MESSAGES = {
+      "conflicting_numeric_bounds" => "conflicting numeric bounds",
+      "conflicting_equalities" => "conflicting equalities",
+      "equality_outside_numeric_range" => "required equality is outside the required numeric range",
+      "nil_conflict" => "conflicting nil requirements",
+      "boolean_literal_conflict" => "conflicting Boolean literal requirements"
+    }.freeze
+
+    # Accumulates the constraints one decision-table rule requires and reports
+    # the first proven contradiction. Subjects never interact with each other.
+    class Solver
+      def initialize
+        @subjects = {}
+      end
+
+      # Returns a reason code when the rule became unsatisfiable, otherwise nil.
+      def add(constraint, truth)
+        constraint = Constraints.symbolize(constraint)
+        return nil unless Constraints.usable?(constraint)
+
+        add_prepared(constraint, truth)
+      end
+
+      # Adds a constraint that has already been symbolized and validated by
+      # +usable?+. Source inventory can use this path after preparing each leaf
+      # once instead of repeating normalization for every solver state.
+      def add_prepared(constraint, truth)
+        state = (@subjects[Constraints.subject_key(constraint[:subject])] ||= new_state)
+        apply(state, constraint[:operator].to_s, constraint[:literal], truth ? true : false)
+      end
+
+      private
+
+      def new_state
+        { lower: nil, upper: nil, equality: nil, exclusions: [], nil_required: nil, truthy: nil,
+          comparisons: {} }
+      end
+
+      def apply(state, operator, literal, truth)
+        if NUMERIC_OPERATORS.include?(operator)
+          key = [operator, literal[:type].to_s, literal[:value]]
+          opposite = state[:comparisons][key]
+          return "conflicting_numeric_bounds" if !opposite.nil? && opposite != truth
+
+          state[:comparisons][key] = truth
+        end
+        case operator
+        when "truthy" then truth ? require_truthy(state) : require_falsey(state)
+        when "==" then truth ? require_equal(state, literal) : exclude(state, literal)
+        when "!=" then truth ? exclude(state, literal) : require_equal(state, literal)
+        # A false inequality is not a closed numeric bound: Ruby values such as
+        # Float::NAN make both sides of a total-order partition false. Keep the
+        # exact same-predicate contradiction above, but otherwise leave false
+        # inequalities unknown unless another true inequality proves a clash.
+        when "<" then truth ? upper(state, literal, false) : nil
+        when "<=" then truth ? upper(state, literal, true) : nil
+        when ">" then truth ? lower(state, literal, false) : nil
+        when ">=" then truth ? lower(state, literal, true) : nil
+        end
+      end
+
+      def require_equal(state, literal)
+        type = literal[:type].to_s
+        # A nil or truthiness clash is reported before a plain equality clash so
+        # the reason code names the most specific contradiction.
+        reason = equality_truthiness_conflict(state, type)
+        return reason if reason
+
+        if state[:equality] && !Constraints.same_literal?(state[:equality], literal)
+          return nil if Constraints.mixed_numeric_literals?(state[:equality], literal)
+
+          return "conflicting_equalities"
+        end
+        return "conflicting_equalities" if state[:exclusions].any? { |item| Constraints.same_literal?(item, literal) }
+
+        state[:equality] = literal
+        state[:nil_required] = type == "nil"
+        return "equality_outside_numeric_range" if Constraints.numeric?(literal) && !within_bounds?(state,
+                                                                                                    literal[:value])
+
+        nil
+      end
+
+      def equality_truthiness_conflict(state, type)
+        if type == "nil"
+          return "nil_conflict" if state[:nil_required] == false || state[:truthy] == true
+        elsif state[:nil_required] == true
+          return "nil_conflict"
+        end
+        return "boolean_literal_conflict" if state[:truthy] == true && type == "false"
+        return "boolean_literal_conflict" if state[:truthy] == false && !FALSEY_TYPES.include?(type)
+
+        nil
+      end
+
+      def exclude(state, literal)
+        if literal[:type].to_s == "nil"
+          return "nil_conflict" if state[:nil_required] == true
+          return "nil_conflict" if state[:equality] && state[:equality][:type].to_s == "nil"
+
+          state[:nil_required] = false
+        elsif state[:equality] && Constraints.same_literal?(state[:equality], literal)
+          return "conflicting_equalities"
+        end
+        state[:exclusions] << literal unless state[:exclusions].any? { |item| Constraints.same_literal?(item, literal) }
+        nil
+      end
+
+      def require_truthy(state)
+        return "boolean_literal_conflict" if state[:truthy] == false
+        return "nil_conflict" if state[:nil_required] == true
+        return "nil_conflict" if state[:equality] && state[:equality][:type].to_s == "nil"
+        return "boolean_literal_conflict" if state[:equality] && state[:equality][:type].to_s == "false"
+
+        state[:truthy] = true
+        state[:nil_required] = false
+        nil
+      end
+
+      def require_falsey(state)
+        return "boolean_literal_conflict" if state[:truthy] == true
+        return "boolean_literal_conflict" if state[:equality] && !FALSEY_TYPES.include?(state[:equality][:type].to_s)
+
+        state[:truthy] = false
+        nil
+      end
+
+      def lower(state, literal, inclusive)
+        return nil unless Constraints.numeric?(literal)
+        return nil unless comparable_bound?(state, literal)
+
+        current = state[:lower]
+        value = literal[:value]
+        if current.nil? || value > current[:value] || (value == current[:value] && !inclusive)
+          state[:lower] = { type: literal[:type].to_s, value: value, inclusive: inclusive }
+        end
+        bounds_conflict(state)
+      end
+
+      def upper(state, literal, inclusive)
+        return nil unless Constraints.numeric?(literal)
+        return nil unless comparable_bound?(state, literal)
+
+        current = state[:upper]
+        value = literal[:value]
+        if current.nil? || value < current[:value] || (value == current[:value] && !inclusive)
+          state[:upper] = { type: literal[:type].to_s, value: value, inclusive: inclusive }
+        end
+        bounds_conflict(state)
+      end
+
+      def bounds_conflict(state)
+        low = state[:lower]
+        high = state[:upper]
+        if low && high && (low[:type] == high[:type])
+          return "conflicting_numeric_bounds" if low[:value] > high[:value]
+          return "conflicting_numeric_bounds" if low[:value] == high[:value] && !(low[:inclusive] && high[:inclusive])
+        end
+        equality = state[:equality]
+        return nil unless equality && Constraints.numeric?(equality) && !within_bounds?(state, equality[:value])
+
+        "equality_outside_numeric_range"
+      end
+
+      def within_bounds?(state, value)
+        low = state[:lower]
+        high = state[:upper]
+        return false if low && low[:type] == state[:equality][:type] &&
+                        (low[:inclusive] ? value < low[:value] : value <= low[:value])
+        return false if high && high[:type] == state[:equality][:type] &&
+                        (high[:inclusive] ? value > high[:value] : value >= high[:value])
+
+        true
+      end
+
+      def comparable_bound?(state, literal)
+        [state[:lower], state[:upper]].compact.all? { |bound| bound[:type] == literal[:type] }
+      end
+    end
+
+    module_function
+
+    # Derives the normalized constraint of one atomic condition, or nil when the
+    # expression is outside the supported vocabulary.
+    def for_node(node)
+      return nil unless node.is_a?(Prism::Node)
+
+      subject = subject_for(node)
+      return { subject: subject, operator: "truthy", literal: nil } if subject
+      return nil unless simple_call?(node)
+
+      name = node.name.to_s
+      return nil_constraint(node) if name == "nil?"
+      return nil unless FLIPPED.key?(name)
+
+      comparison_constraint(node, name)
+    end
+
+    def comparison_constraint(node, name)
+      argument = single_argument(node)
+      return nil unless argument
+
+      subject = subject_for(node.receiver)
+      if subject
+        literal = literal_for(argument)
+        operator = name
+      else
+        subject = subject_for(argument)
+        literal = subject && literal_for(node.receiver)
+        operator = FLIPPED.fetch(name)
+      end
+      return nil unless subject && literal
+      return nil if NUMERIC_OPERATORS.include?(operator) && !NUMERIC_TYPES.include?(literal[:type])
+
+      { subject: subject, operator: operator, literal: literal }
+    end
+
+    def nil_constraint(node)
+      return nil unless node.arguments.nil?
+
+      subject = subject_for(node.receiver)
+      return nil unless subject
+
+      { subject: subject, operator: "==", literal: { type: "nil", value: nil } }
+    end
+
+    def simple_call?(node)
+      node.is_a?(Prism::CallNode) && !node.safe_navigation? && node.block.nil?
+    end
+
+    def single_argument(node)
+      arguments = node.arguments&.arguments
+      return nil unless arguments && arguments.length == 1
+
+      argument = arguments.first
+      return nil if argument.is_a?(Prism::SplatNode) || argument.is_a?(Prism::KeywordHashNode) ||
+                    argument.is_a?(Prism::BlockArgumentNode)
+
+      argument
+    end
+
+    # Only unambiguously identifiable storage locations become subjects.
+    # Method-call receivers stay unsupported: a repeated call may return a
+    # different value or have side effects (see the v1 constraint scope).
+    def subject_for(node)
+      case node
+      when Prism::LocalVariableReadNode then { kind: "local", name: node.name.to_s }
+      when Prism::InstanceVariableReadNode then { kind: "instance", name: node.name.to_s }
+      when Prism::ClassVariableReadNode then { kind: "class", name: node.name.to_s }
+      when Prism::GlobalVariableReadNode then { kind: "global", name: node.name.to_s }
+      when Prism::ConstantReadNode then { kind: "constant", name: node.name.to_s }
+      end
+    end
+
+    # String equality stays unsupported in v1 so that encoding and mutability
+    # questions cannot turn into an impossibility claim.
+    def literal_for(node)
+      case node
+      when Prism::IntegerNode then { type: "integer", value: node.value }
+      when Prism::FloatNode
+        return nil unless node.value.finite?
+
+        { type: "float", value: node.value }
+      when Prism::SymbolNode then { type: "symbol", value: node.unescaped.to_s }
+      when Prism::NilNode then { type: "nil", value: nil }
+      when Prism::TrueNode then { type: "true", value: true }
+      when Prism::FalseNode then { type: "false", value: false }
+      end
+    end
+
+    def usable?(constraint)
+      return false unless constraint.is_a?(Hash)
+
+      subject = symbolize(constraint[:subject])
+      operator = constraint[:operator].to_s
+      return false unless subject.is_a?(Hash) && SUBJECT_KINDS.include?(subject[:kind].to_s)
+      return false if subject[:name].to_s.empty?
+      return false unless OPERATORS.include?(operator)
+      return true if operator == "truthy"
+
+      literal = symbolize(constraint[:literal])
+      return false unless literal.is_a?(Hash) && LITERAL_TYPES.include?(literal[:type].to_s)
+      return false if NUMERIC_OPERATORS.include?(operator) && !NUMERIC_TYPES.include?(literal[:type].to_s)
+      return false unless valid_literal_value?(literal)
+
+      true
+    end
+
+    def valid_literal_value?(literal)
+      case literal[:type].to_s
+      when "integer" then literal[:value].is_a?(Integer)
+      when "float" then literal[:value].is_a?(Float) && literal[:value].finite?
+      when "symbol" then literal[:value].is_a?(String)
+      when "nil" then literal[:value].nil?
+      when "true" then literal[:value] == true
+      when "false" then literal[:value] == false
+      else false
+      end
+    end
+
+    def subject_key(subject)
+      subject = symbolize(subject)
+      [subject[:kind].to_s, subject[:name].to_s]
+    end
+
+    def numeric?(literal) = NUMERIC_TYPES.include?(literal[:type].to_s)
+
+    def same_literal?(left, right)
+      return left[:value] == right[:value] if left[:type].to_s == right[:type].to_s
+      return false unless mixed_numeric_literals?(left, right)
+
+      integer, float = if left[:type].to_s == "integer"
+                         [left[:value], right[:value]]
+                       else
+                         [right[:value], left[:value]]
+                       end
+      float.finite? && float.to_r == integer
+    end
+
+    def mixed_numeric_literals?(left, right)
+      numeric?(left) && numeric?(right) && left[:type].to_s != right[:type].to_s
+    end
+
+    def message(reason) = REASON_MESSAGES.fetch(reason.to_s, reason.to_s.tr("_", " "))
+
+    def symbolize(value)
+      return value unless value.is_a?(Hash)
+
+      value.each_with_object({}) do |(key, item), result|
+        result[key.to_sym] = item.is_a?(Hash) ? symbolize(item) : item
+      end
+    end
+  end
+end

data/lib/branchproof/coverage_index.rb

@@ -7,7 +7,7 @@ require "pathname"
 module Branchproof
   # Derives condition- and test-oriented rows from one report document.
   class CoverageIndex
-    attr_reader :conditions, :tests
+    attr_reader :conditions, :alternatives, :tests
 
     def initialize(document:)
       @document = symbolize(document || {})
@@ -27,9 +27,14 @@ module Branchproof
         @tests_by_id[id] = (@tests_by_id[id] || {}).merge(test) unless id.empty?
       end
       @conditions = build_conditions.freeze
+      @alternatives = build_alternatives.freeze
       @tests = build_tests.freeze
     end
 
+    def decision_tables
+      @decision_tables ||= build_decision_tables.freeze
+    end
+
     private
 
     def build_conditions
@@ -62,7 +67,7 @@ module Branchproof
             id: condition[:id], decision_id: decision[:id], index: condition[:index],
             expression: condition[:expression],
             line: condition[:line], column: condition[:column], relative_path: relative_path(source[:relative_path]),
-            decision_expression: decision[:expression],
+            decision_expression: decision[:expression], kind: decision_kind(decision), context: decision[:context],
             status: @document[:analysis] ? (result[:status] || "NOT_PROVEN") : "NOT CALCULATED",
             observed_true: test_ids(observations[true]), observed_false: test_ids(observations[false]),
             short_circuited: test_ids(observations[:short_circuited]),
@@ -80,12 +85,94 @@ module Branchproof
       end
     end
 
+    def build_alternatives
+      records(@inventory, :decisions).flat_map do |decision|
+        next [] if decision[:support_status].to_s == "UNSUPPORTED"
+        next [] if boolean_decision?(decision)
+
+        source = @source_units_by_id[decision[:source_id].to_s] || {}
+        coverage = symbolize(analysis_for(decision)[:coverage] || {})[:alternative] || {}
+        coverage_rows = records(coverage, :alternatives).to_h { |row| [row[:alternative_id].to_s, row] }
+        vectors = @vectors_by_decision[decision[:id].to_s] || []
+        records(decision, :alternatives).map do |alternative|
+          alternative = symbolize(alternative)
+          evidence = { selected: [], not_selected: [], skipped: [] }
+          vectors.each do |vector|
+            value = vector_values(vector)[alternative[:index].to_i]
+            state = if value.nil?
+                      :skipped
+                    else
+                      (value ? :selected : :not_selected)
+                    end
+            evidence[state] << vector
+          end
+          row = symbolize(coverage_rows[alternative[:id].to_s] || {})
+          {
+            id: alternative[:id], alternative_id: alternative[:id], decision_id: decision[:id],
+            index: alternative[:index], expression: alternative[:expression],
+            line: alternative[:line], column: alternative[:column],
+            relative_path: relative_path(source[:relative_path]),
+            decision_expression: decision[:expression], kind: decision_kind(decision),
+            context: decision[:context],
+            status: @document[:analysis] ? alternative_status(row, evidence) : "NOT CALCULATED",
+            selected: row[:selected] || evidence_bucket(evidence[:selected]),
+            not_selected: row[:not_selected] || evidence_bucket(evidence[:not_selected]),
+            skipped: row[:skipped] || evidence_bucket(evidence[:skipped]),
+            vectors: evidence, missing: missing_alternative?(coverage, alternative)
+          }
+        end
+      end
+    end
+
+    def build_decision_tables
+      rows = records(@inventory, :decisions).filter_map do |decision|
+        next unless boolean_decision?(decision)
+
+        table = analysis_for(decision)[:decision_table] || {}
+        next if table.empty?
+
+        source = @source_units_by_id[decision[:source_id].to_s] || {}
+        {
+          decision_id: decision[:id], decision_expression: decision[:expression],
+          context: decision[:context], kind: decision_kind(decision),
+          relative_path: relative_path(source[:relative_path]), line: decision[:line],
+          conditions: Array(decision[:conditions]).map { |condition| condition[:expression].to_s },
+          status: table[:status], reason: table[:reason],
+          schema_version: table[:schema_version], constraint_analysis_version: table[:constraint_analysis_version],
+          rules: Array(table[:rules]),
+          generated_rules: table[:generated_rules].to_i, impossible_rules: table[:impossible_rules].to_i,
+          required_rules: table[:required_rules].to_i, covered_rules: table[:covered_rules].to_i,
+          missing_rules: table[:missing_rules].to_i, percentage: table[:percentage],
+          coverage_status: table[:coverage_status], reachability_analyzed: table[:reachability_analyzed]
+        }
+      end
+      rows.sort_by { |row| [row[:relative_path].to_s, row[:line].to_i, row[:decision_id].to_s] }
+    end
+
     def build_tests
       by_id = @tests_by_id.transform_values do |test|
         { id: test[:id], name: display_name(test), relative_path: test_location(test)[0], line: test_location(test)[1],
           status: test[:status], phases: Array(test[:phase_counts]).to_h.keys.sort,
           observations: [], owns_witness: false }
       end
+      @alternatives.each do |alternative|
+        alternative[:vectors].each do |kind, vectors|
+          vectors.each do |vector|
+            Array(vector[:test_ids]).each do |id|
+              row = by_id[id.to_s] ||= { id: id, name: id, relative_path: nil, line: nil, status: "unknown",
+                                         phases: [], observations: [], owns_witness: false }
+              phase_map = symbolize(vector[:phases_by_test] || {})
+              phases = phase_map[id.to_s] || phase_map[id.to_sym] || []
+              row[:phases] |= Array(phases).map(&:to_s)
+              row[:observations] << { alternative_id: alternative[:id], expression: alternative[:expression],
+                                      relative_path: alternative[:relative_path], line: alternative[:line],
+                                      value: kind == :skipped ? nil : (kind == :selected), kind: :alternative,
+                                      alternative_state: kind.to_s, phases: phases.map(&:to_s).sort,
+                                      owns_witness: false }
+            end
+          end
+        end
+      end
       @conditions.each do |condition|
         condition[:vectors].each do |kind, vectors|
           next if kind == :unattributed
@@ -118,6 +205,36 @@ module Branchproof
       @analysis_by_decision[decision[:id].to_s] || {}
     end
 
+    def boolean_decision?(decision)
+      decision_kind(decision) == "boolean"
+    end
+
+    def decision_kind(decision)
+      kind = decision[:kind].to_s
+      kind.empty? ? "boolean" : kind
+    end
+
+    def evidence_bucket(vectors)
+      evidence = vectors.map do |vector|
+        { vector_id: vector[:id].to_s, test_ids: Array(vector[:test_ids]).map(&:to_s).uniq.sort,
+          unattributed_count: vector[:unattributed_count].to_i }
+      end
+      { observed: !vectors.empty?, vector_ids: evidence.map { |item| item[:vector_id] }.uniq.sort,
+        test_ids: evidence.flat_map { |item| item[:test_ids] }.uniq.sort,
+        unattributed_count: evidence.sum { |item| item[:unattributed_count] } }
+    end
+
+    def missing_alternative?(coverage, alternative)
+      Array(coverage[:missing_alternatives]).map(&:to_s).include?(alternative[:id].to_s)
+    end
+
+    def alternative_status(row, evidence)
+      status = row[:status].to_s
+      return status unless status.empty?
+
+      evidence[:selected].empty? ? "unexecuted" : "covered"
+    end
+
     def supporting_set_for(decision_id)
       Array(@document[:minima] || @document["minima"]).filter_map do |minimum|
         minimum = symbolize(minimum)
@@ -145,7 +262,7 @@ module Branchproof
 
     def test_ids(vectors) = vectors.flat_map { |vector| Array(vector[:test_ids]) }.map(&:to_s).uniq.sort
     def vector_values(vector) = Array(vector[:values])
-    def records(hash, key) = Array(hash[key] || hash[key.to_s]).map { |item| symbolize(item) }
+    def records(hash, key) = Array(hash[key] || hash[key.to_s])
 
     def display_name(test)
       return "#{test[:class_name]}##{test[:method_name]}" if test[:class_name] && test[:method_name]