branchproof 0.7.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

@@ -31,6 +31,10 @@ module Branchproof
       @tests = build_tests.freeze
     end
 
+    def decision_tables
+      @decision_tables ||= build_decision_tables.freeze
+    end
+
     private
 
     def build_conditions
@@ -120,6 +124,31 @@ module Branchproof
       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],
@@ -233,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]

data/lib/branchproof/decision_syntax.rb

@@ -1,25 +1,36 @@
 # frozen_string_literal: true
 
+require "prism"
+
 module Branchproof
   # Discovers control-flow expressions whose truth is not represented by an
   # ordinary Prism IfNode.  The records intentionally contain byte ranges and
   # scalar metadata only; Prism nodes must not escape the source pass.
   module DecisionSyntax
-    OR_WRITE_NODE_NAMES = %w[
-      CallOrWriteNode ClassVariableOrWriteNode ConstantOrWriteNode
-      ConstantPathOrWriteNode GlobalVariableOrWriteNode IndexOrWriteNode
-      InstanceVariableOrWriteNode LocalVariableOrWriteNode
-    ].freeze
+    # Some of these node classes were added in later Prism 1.x releases, so
+    # look them up by name and skip any that this Prism version lacks.
+    def self.node_classes(*names)
+      names.filter_map { |name| Prism.const_get(name) if Prism.const_defined?(name) }.to_set.freeze
+    end
+    private_class_method :node_classes
 
-    AND_WRITE_NODE_NAMES = %w[
-      CallAndWriteNode ClassVariableAndWriteNode ConstantAndWriteNode
-      ConstantPathAndWriteNode GlobalVariableAndWriteNode IndexAndWriteNode
-      InstanceVariableAndWriteNode LocalVariableAndWriteNode
-    ].freeze
+    OR_WRITE_NODE_CLASSES = node_classes(
+      :CallOrWriteNode, :ClassVariableOrWriteNode, :ConstantOrWriteNode,
+      :ConstantPathOrWriteNode, :GlobalVariableOrWriteNode, :IndexOrWriteNode,
+      :InstanceVariableOrWriteNode, :LocalVariableOrWriteNode
+    )
 
-    def flow_decisions_for(program, bytes, source_id, file_reasons = [], encoding = "UTF-8")
-      nodes = []
-      walk(program) { |node| nodes << node if flow_decision_node?(node) }
+    AND_WRITE_NODE_CLASSES = node_classes(
+      :CallAndWriteNode, :ClassVariableAndWriteNode, :ConstantAndWriteNode,
+      :ConstantPathAndWriteNode, :GlobalVariableAndWriteNode, :IndexAndWriteNode,
+      :InstanceVariableAndWriteNode, :LocalVariableAndWriteNode
+    )
+
+    # nodes: flow-decision nodes already collected by a caller's own AST walk
+    # (Source merges this discovery into one pass). Falls back to its own
+    # walk when nothing is passed in, so this method still works standalone.
+    def flow_decisions_for(program, bytes, source_id, file_reasons = [], encoding = "UTF-8", nodes: nil)
+      nodes ||= collect_flow_decision_nodes(program)
       nodes.sort_by { |node| [node.location.start_offset, node.location.length] }.map do |node|
         build_flow_decision(node, bytes, source_id, file_reasons, encoding)
       end
@@ -27,6 +38,12 @@ module Branchproof
 
     private
 
+    def collect_flow_decision_nodes(program)
+      nodes = []
+      walk(program) { |node| nodes << node if flow_decision_node?(node) }
+      nodes
+    end
+
     def flow_decision_node?(node)
       return true if node.is_a?(Prism::CaseNode) && node.predicate
       return true if node.is_a?(Prism::CaseMatchNode)
@@ -38,8 +55,7 @@ module Branchproof
     end
 
     def assignment_node?(node)
-      OR_WRITE_NODE_NAMES.include?(node.class.name.split("::").last) ||
-        AND_WRITE_NODE_NAMES.include?(node.class.name.split("::").last)
+      OR_WRITE_NODE_CLASSES.include?(node.class) || AND_WRITE_NODE_CLASSES.include?(node.class)
     end
 
     def build_flow_decision(node, bytes, source_id, file_reasons, encoding)