branchproof 0.11.0 → 0.12.0

data/lib/branchproof/report_selection.rb

@@ -6,21 +6,27 @@ 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
+    attr_reader :focus, :top, :decision_ids
 
-    def initialize(focus: nil, top: nil)
+    def initialize(focus: nil, top: nil, decision_ids: nil)
       @focus = normalize_focus(focus)
       @top = normalize_top(top)
+      @decision_ids = decision_ids.nil? ? nil : Array(decision_ids).map(&:to_s).uniq.freeze
+      @decision_id_set = @decision_ids&.to_h { |id| [id, true] }
     end
 
     def active?
-      !@focus.nil? || !@top.nil?
+      !@focus.nil? || !@top.nil? || !@decision_ids.nil?
     end
 
     def focus_active?
       !@focus.nil?
     end
 
+    def decision_filter_active?
+      focus_active? || !@decision_ids.nil?
+    end
+
     def focus_label
       return unless @focus
 
@@ -37,11 +43,26 @@ module Branchproof
       end
     end
 
+    def selected_decision_ids(document)
+      ids = decision_ids
+      focus_ids = matching_decision_ids(document) if focus_active?
+      return focus_ids unless ids
+      return ids unless focus_active?
+
+      focus_set = focus_ids.to_h { |id| [id, true] }
+      ids.select { |id| focus_set.key?(id) }
+    end
+
     def filter_decisions(decisions, inventory: {})
-      return decisions unless focus_active?
+      return decisions unless decision_filter_active?
 
       sources = source_map(inventory)
-      decisions.select { |decision| matches_decision?(decision, sources) }
+      decisions.select do |decision|
+        id = fetch(decision, :id).to_s
+        in_scope = !@decision_id_set || @decision_id_set.key?(id)
+        in_focus = !focus_active? || matches_decision?(decision, sources)
+        in_scope && in_focus
+      end
     end
 
     def limit(items)

data/lib/branchproof/runtime.rb

@@ -7,6 +7,7 @@ require_relative "exception_runtime"
 require_relative "default_runtime"
 require_relative "value_runtime"
 require_relative "iteration_runtime"
+require_relative "fallback_runtime"
 
 module Branchproof
   # Process-local execution recorder. It deliberately never coerces or stores
@@ -19,6 +20,7 @@ module Branchproof
     extend DefaultRuntime
     extend ValueRuntime
     extend IterationRuntime
+    extend FallbackRuntime
 
     FRAME_STATE_KEY = :branchproof_runtime_frame_state
 

data/lib/branchproof/saved_report.rb

@@ -8,13 +8,14 @@ require "json"
 # rubocop:disable-next Lint/RedundantRequireStatement -- supports standalone core entry
 require "set"
 require_relative "coverage_policy"
+require_relative "changed_coverage"
 require_relative "decision_table"
 
 module Branchproof
   # Reads and validates a persisted JSON report without loading the project.
   class SavedReport
-    SUPPORTED_SCHEMAS = %w[1.0 1.1 1.2 1.3 1.4].freeze
-    STRICT_FLOW_SCHEMAS = %w[1.2 1.3 1.4].freeze
+    SUPPORTED_SCHEMAS = %w[1.0 1.1 1.2 1.3 1.4 1.5 1.6 1.7].freeze
+    STRICT_FLOW_SCHEMAS = %w[1.2 1.3 1.4 1.5 1.6 1.7].freeze
     DECISION_TABLE_STATUSES = %w[calculated not_calculated].freeze
     RULE_CONDITION_VALUES = DecisionTable::CONDITION_VALUES
     RULE_COVERAGE_STATUSES = DecisionTable::COVERAGE_STATUSES
@@ -49,7 +50,8 @@ module Branchproof
       @schema_version = @document["schema_version"]
       schema = @schema_version
       fail_with("unsupported schema version") unless SUPPORTED_SCHEMAS.include?(schema)
-      missing = REQUIRED_FIELDS.reject { |field| @document.key?(field) }
+      required_fields = REQUIRED_FIELDS + (@schema_version == "1.7" ? ["collation"] : [])
+      missing = required_fields.reject { |field| @document.key?(field) }
       fail_with("missing field: #{missing.first}") unless missing.empty?
       fail_with("criterion version mismatch") unless @document["criterion_version"] == CRITERION_VERSION
       fail_with("run_ids must be an array of strings") unless strings?(@document["run_ids"])
@@ -62,7 +64,14 @@ module Branchproof
       validate_completeness(@document.dig("observations", "completeness"))
       validate_completeness(@document.dig("analysis", "completeness")) if @document["analysis"]
       validate_coverage_policy
+      validate_changed_scope
+      validate_changed_coverage_policy
       validate_optional_sections
+      if @schema_version == "1.7"
+        validate_collation
+      elsif @document.key?("collation")
+        fail_with("collation is unsupported by this report schema")
+      end
       validate_analysis_coverage
       @document
     end
@@ -220,7 +229,7 @@ module Branchproof
           fail_with("nonboolean condition results must be empty") unless results.empty?
           validate_nonboolean_analysis(decision, inventory_decision)
         elsif decision.key?("decision_table")
-          unless %w[1.3 1.4].include?(@schema_version)
+          unless %w[1.3 1.4 1.5 1.6 1.7].include?(@schema_version)
             fail_with("decision tables are unsupported in legacy report schemas")
           end
           validate_decision_table(decision["decision_table"], inventory_decision)
@@ -632,7 +641,7 @@ module Branchproof
 
     def validate_coverage_policy
       policy = @document["coverage_policy"]
-      fail_with("missing field: coverage_policy") if @schema_version == "1.4" && !policy
+      fail_with("missing field: coverage_policy") if %w[1.4 1.5 1.6 1.7].include?(@schema_version) && !policy
       return if policy.nil?
 
       fail_with("coverage_policy must be an object") unless hash_with_string_keys?(policy)
@@ -652,6 +661,315 @@ module Branchproof
       fail_with(e.message.sub(/\Ainvalid saved report: /, ""))
     end
 
+    def validate_changed_scope
+      scope_present = @document.key?("changed_scope")
+      summary_present = @document.key?("changed_coverage")
+      return if @schema_version == "1.7" && !scope_present && !summary_present
+
+      unless %w[1.5 1.6 1.7].include?(@schema_version)
+        fail_with("changed scope is unsupported by this report schema") if scope_present || summary_present
+        return
+      end
+      fail_with("missing field: changed_scope") unless scope_present
+      fail_with("missing field: changed_coverage") unless summary_present
+
+      scope = @document["changed_scope"]
+      fail_with("changed_scope must be an object") unless hash_with_string_keys?(scope)
+      fail_with("changed_scope version is unsupported") unless scope["version"] == "1.0"
+      unless nonempty_string?(scope["requested_ref"]) && !scope["requested_ref"].include?("\0")
+        fail_with("changed_scope requested_ref must be a usable Git ref string")
+      end
+      unless scope["base_commit"].is_a?(String) && scope["base_commit"].match?(/\A(?:[0-9a-f]{40}|[0-9a-f]{64})\z/i)
+        fail_with("changed_scope base_commit must be a full commit id")
+      end
+      fail_with("changed_scope comparison is invalid") unless scope["comparison"] == "tracked_worktree"
+      fail_with("changed_scope untracked policy is invalid") unless scope["untracked"] == "excluded"
+      fail_with("changed_scope status is invalid") unless %w[complete empty].include?(scope["status"])
+      files = scope["files"]
+      fail_with("changed_scope files must be an array") unless files.is_a?(Array)
+      ids = scope["decision_ids"]
+      fail_with("changed_scope decision_ids must be an array of strings") unless strings?(ids)
+      fail_with("duplicate changed decision id") unless ids.uniq.length == ids.length
+      fail_with("changed_scope status does not match selected decisions") if (scope["status"] == "empty") != ids.empty?
+
+      changed_paths = validate_changed_files(files)
+      inventory_order = @decision_ids
+      fail_with("unknown changed decision id") unless (ids - inventory_order).empty?
+      fail_with("changed decision ids are out of inventory order") unless ids == inventory_order.select do |id|
+        ids.include?(id)
+      end
+      current_paths = @document.dig("source_inventory", "source_units").to_h do |source|
+        [source["source_id"], source["relative_path"]]
+      end
+      selected_on_changed_path = ids.all? do |id|
+        decision = @decisions_by_id.fetch(id)
+        path = current_paths[decision["source_id"]]
+        path && changed_paths.include?(path)
+      end
+      fail_with("changed decision does not belong to a current changed file") unless selected_on_changed_path
+
+      expected = JSON.parse(JSON.generate(ChangedCoverage.call(document: @document, scope: scope)))
+      actual = JSON.parse(JSON.generate(@document["changed_coverage"]))
+      fail_with("changed_coverage does not match captured analysis") unless actual == expected
+    end
+
+    def validate_changed_coverage_policy
+      policy_present = @document.key?("changed_coverage_policy")
+      if @schema_version == "1.6"
+        fail_with("missing field: changed_coverage_policy") unless policy_present
+      elsif @schema_version == "1.7"
+        return unless policy_present
+
+        fail_with("changed policy requires captured scope") unless @document["changed_scope"]
+      elsif policy_present
+        fail_with("changed_coverage_policy is unsupported by this report schema")
+      else
+        return
+      end
+
+      policy = @document["changed_coverage_policy"]
+      fail_with("changed_coverage_policy must be an object") unless hash_with_string_keys?(policy)
+      minimum = policy["minimum_changed"]
+      fail_with("changed_coverage_policy minimum_changed must be an object") unless hash_with_string_keys?(minimum)
+      normalized = CoveragePolicy.normalize(minimum)
+      fail_with("changed_coverage_policy minimum_changed must not be empty") if normalized.empty?
+      fail_with("changed_coverage_policy status must be a string") unless policy["status"].is_a?(String)
+      fail_with("changed_coverage_policy gates must be an array") unless policy["gates"].is_a?(Array)
+      expected = ChangedCoveragePolicy.new(minimum_changed: normalized).call(
+        document: @document, scope: @document["changed_scope"]
+      )
+      actual = JSON.parse(JSON.generate(policy))
+      expected = JSON.parse(JSON.generate(expected))
+      fail_with("changed_coverage_policy does not match captured analysis") unless actual == expected
+    rescue ArgumentError => e
+      fail_with(e.message.sub(/\Ainvalid saved report: /, ""))
+    end
+
+    def validate_collation
+      data = @document["collation"]
+      fail_with("collation must be an object") unless hash_with_string_keys?(data)
+      fail_with("collation version is unsupported") unless data["version"] == "1.0"
+      statuses = %w[complete incomplete unknown]
+      status = data["collection_status"]
+      fail_with("collation collection_status is invalid") unless statuses.include?(status)
+      expected = data["expected_shards"]
+      if !expected.nil? && (!strings?(expected) || expected.empty? || expected.any? { |id| !nonempty_string?(id) } ||
+                            expected.uniq.length != expected.length)
+        fail_with("collation expected_shards must be null or unique nonempty IDs")
+      end
+      missing = data["missing_shards"]
+      unless strings?(missing) && missing.uniq.length == missing.length
+        fail_with("collation missing_shards must be unique IDs")
+      end
+      shards = data["shards"]
+      fail_with("collation shards must be a nonempty array") unless shards.is_a?(Array) && !shards.empty?
+      ids = []
+      digests = []
+      run_ids = []
+      shard_baselines = []
+      shards.each do |shard|
+        fail_with("invalid collation shard") unless hash_with_string_keys?(shard)
+        id = shard["id"]
+        fail_with("collation shard ID must be a nonempty string") unless nonempty_string?(id)
+        ids << id
+        paths = shard["paths"]
+        valid_paths = strings?(paths) && !paths.empty? && paths.all? { |path| nonempty_string?(path) }
+        fail_with("collation shard paths must be nonempty strings") unless valid_paths
+        digest = shard["report_digest"]
+        unless digest.is_a?(String) && digest.match?(/\A[0-9a-f]{64}\z/)
+          fail_with("collation report digest must be SHA-256")
+        end
+        digests << digest
+        shard_runs = shard["run_ids"]
+        valid_run_ids = strings?(shard_runs) && !shard_runs.empty? &&
+                        shard_runs.all? { |value| nonempty_string?(value) } &&
+                        shard_runs.uniq.length == shard_runs.length
+        fail_with("collation shard run_ids must be nonempty unique IDs") unless valid_run_ids
+        run_ids.concat(shard_runs)
+        baseline = shard["baseline"]
+        fail_with("invalid collation shard baseline") unless hash_with_string_keys?(baseline)
+        fail_with("collation shard baseline status is invalid") unless %w[PASSED FAILED ERROR
+                                                                          INCOMPLETE].include?(baseline["status"])
+        %w[executed_tests failed_tests skipped_tests].each do |field|
+          unless baseline[field].is_a?(Integer) && baseline[field] >= 0
+            fail_with("collation shard baseline #{field} must be nonnegative")
+          end
+        end
+        fail_with("collation shard baseline finalized must be boolean") unless [true,
+                                                                                false].include?(baseline["finalized"])
+        fail_with("collation shard baseline status must be a string") unless baseline["status"].is_a?(String)
+        fail_with("collation shard failed and skipped counts exceed executed tests") if
+          baseline["failed_tests"] + baseline["skipped_tests"] > baseline["executed_tests"]
+        fail_with("PASSED collation shard cannot contain failures") if baseline["status"] == "PASSED" &&
+                                                                       baseline["failed_tests"].positive?
+        fail_with("zero-test collation shard cannot pass") if baseline["status"] == "PASSED" &&
+                                                              baseline["executed_tests"].zero?
+        completeness = shard["completeness"]
+        validate_completeness(completeness)
+        fail_with("collation shard run_metadata must be an object") unless hash_with_string_keys?(shard["run_metadata"])
+        shard_baselines << baseline
+      end
+      fail_with("duplicate collation shard ID") unless ids.uniq.length == ids.length
+      fail_with("duplicate collation report digest") unless digests.uniq.length == digests.length
+      fail_with("overlapping collation run IDs") unless run_ids.uniq.length == run_ids.length
+      fail_with("collation run IDs do not match report run_ids") unless @document["run_ids"].sort == run_ids.sort
+      observations = @document["observations"]
+      unless observations["run_ids"] == @document["run_ids"]
+        fail_with("collation observation run_ids do not match report run_ids")
+      end
+      validate_collated_test_statuses(observations)
+      expected_missing = expected ? expected - ids : []
+      fail_with("collation contains undeclared shard IDs") if expected && (ids - expected).any?
+      fail_with("collation missing_shards do not match expected IDs") unless missing == expected_missing
+      expected_status = if expected.nil?
+                          "unknown"
+                        elsif expected_missing.empty?
+                          "complete"
+                        else
+                          "incomplete"
+                        end
+      fail_with("collation collection status does not match shard IDs") unless status == expected_status
+      counts = %w[executed_tests failed_tests skipped_tests].to_h do |field|
+        [field, shard_baselines.sum { |baseline| baseline.fetch(field) }]
+      end
+      counts.each do |field, value|
+        next if @document.dig("baseline", field) == value
+
+        fail_with("collation aggregate #{field} does not match provenance")
+      end
+      forced_incomplete = status != "complete" || shard_baselines.any? do |baseline|
+        baseline["status"] == "INCOMPLETE" || baseline["finalized"] != true
+      end || shards.any? { |shard| shard.fetch("completeness").values.any? { |complete| complete != true } }
+      forced_error = shard_baselines.any? { |baseline| baseline["status"] == "ERROR" }
+      forced_failed = shard_baselines.any? do |baseline|
+        baseline["status"] == "FAILED"
+      end || counts.fetch("failed_tests").positive?
+      aggregate_status = if forced_error
+                           "ERROR"
+                         elsif forced_incomplete
+                           "INCOMPLETE"
+                         elsif forced_failed
+                           "FAILED"
+                         else
+                           "PASSED"
+                         end
+      fail_with("collation aggregate baseline status does not match provenance") unless
+        @document.dig("baseline", "status") == aggregate_status
+      fail_with("collation aggregate finalized does not match status") unless
+        @document.dig("baseline", "finalized") == %w[PASSED FAILED].include?(aggregate_status)
+      if status != "complete"
+        %w[completeness observations analysis].each do |section|
+          bits = if section == "completeness"
+                   @document[section]
+                 elsif section == "observations"
+                   observations["completeness"]
+                 else
+                   @document.dig(section, "completeness")
+                 end
+          if bits && bits["observation"] == true
+            fail_with("incomplete collection cannot claim observation completeness")
+          end
+        end
+      end
+      %w[observation attribution analysis].each do |field|
+        next unless shards.any? { |shard| shard.dig("completeness", field) == false }
+
+        completeness_restored = @document.dig("completeness", field) == true ||
+                                @document.dig("observations", "completeness", field) == true ||
+                                (@document["analysis"] && @document.dig("analysis", "completeness", field) == true)
+        fail_with("collation cannot restore false completeness") if completeness_restored
+      end
+    end
+
+    def validate_collated_test_statuses(observations)
+      test_statuses = lambda do |tests, section|
+        tests.each do |test|
+          status = test["status"]
+          unless %w[passed failed skipped unknown running].include?(status)
+            fail_with("collation #{section} test status is invalid")
+          end
+        end
+      end
+      observed_tests = observations.fetch("tests")
+      baseline_tests = @document.dig("baseline", "tests") || []
+      test_statuses.call(observed_tests, "observation")
+      test_statuses.call(baseline_tests, "baseline")
+      baseline_by_id = baseline_tests.to_h { |test| [test.fetch("id"), test] }
+      observed_tests.each do |test|
+        baseline_test = baseline_by_id[test.fetch("id")]
+        next unless baseline_test
+        next if baseline_test["status"] == test["status"]
+
+        fail_with("collation baseline and observation test statuses disagree")
+      end
+      failed = observed_tests.count { |test| test["status"] == "failed" }
+      skipped = observed_tests.count { |test| test["status"] == "skipped" }
+      baseline = @document.fetch("baseline")
+      if failed > baseline.fetch("failed_tests") || skipped > baseline.fetch("skipped_tests")
+        fail_with("collation observed failures or skips exceed baseline counts")
+      end
+      if baseline["status"] == "PASSED" && observed_tests.any? do |test|
+           !%w[passed skipped].include?(test["status"])
+         end
+        fail_with("PASSED collation cannot contain failed, unknown, or running tests")
+      end
+    end
+
+    def validate_changed_files(files)
+      seen_paths = {}
+      current_paths = []
+      files.each do |file|
+        fail_with("invalid changed file") unless hash_with_string_keys?(file)
+        status = file["status"]
+        simple_status = %w[A D M T U X B].include?(status)
+        scored_status = status.is_a?(String) && status.match?(/\A[RC]\d{1,3}\z/) &&
+                        status[1..].to_i.between?(0, 100)
+        valid_status = simple_status || scored_status
+        fail_with("changed file status is invalid") unless valid_status
+        path = file["path"]
+        validate_changed_path(path, "changed file path")
+        fail_with("duplicate changed file path") if seen_paths.key?(path)
+        seen_paths[path] = true
+        rename = status.start_with?("R", "C")
+        old_path = file["old_path"]
+        if rename
+          validate_changed_path(old_path, "changed file old_path")
+          fail_with("rename paths must differ") if old_path == path
+        elsif file.key?("old_path")
+          fail_with("old_path is only valid for renamed files")
+        end
+        current_paths << path unless status == "D"
+        hunks = file["hunks"]
+        fail_with("changed file hunks must be an array") unless hunks.is_a?(Array)
+        hunks.each { |hunk| validate_changed_hunk(hunk) }
+      end
+      current_paths
+    end
+
+    def validate_changed_path(path, field)
+      unless path.is_a?(String) && path.encoding == Encoding::UTF_8 && path.valid_encoding? && !path.empty? &&
+             !path.include?("\0") && !path.start_with?("/") && !path.split("/").intersect?(%w[. ..])
+        fail_with("#{field} must be a safe UTF-8 relative path")
+      end
+    end
+
+    def validate_changed_hunk(hunk)
+      fail_with("invalid changed hunk") unless hash_with_string_keys?(hunk)
+      %w[old_start old_count new_start new_count].each do |field|
+        value = hunk[field]
+        fail_with("changed hunk #{field} must be a nonnegative integer") unless value.is_a?(Integer) && value >= 0
+      end
+      %w[old new].each do |side|
+        start = hunk["#{side}_start"]
+        count = hunk["#{side}_count"]
+        fail_with("changed hunk #{side} range has an invalid start") if count.positive? && start.zero?
+      end
+    end
+
+    def nonempty_string?(value)
+      value.is_a?(String) && !value.empty?
+    end
+
     def validate_phases(vector)
       phases = vector["phases_by_test"]
       return if phases.nil?

data/lib/branchproof/source.rb

@@ -6,6 +6,7 @@ require "prism"
 require_relative "decision_syntax"
 require_relative "iteration_syntax"
 require_relative "exception_syntax"
+require_relative "fallback_syntax"
 require_relative "default_syntax"
 require_relative "value_syntax"
 require_relative "constraints"
@@ -19,9 +20,19 @@ module Branchproof
     # family. Additional modules can follow the same seam.
     include IterationSyntax
     include ExceptionSyntax
+    include FallbackSyntax
     prepend DefaultSyntax
     prepend ValueSyntax
 
+    # Strings, symbols, and numbers are always truthy. A regexp literal in a
+    # condition matches against $_, so its truth is not static.
+    ALWAYS_TRUTHY_LITERALS = [
+      Prism::TrueNode, Prism::StringNode, Prism::InterpolatedStringNode,
+      Prism::SymbolNode, Prism::InterpolatedSymbolNode, Prism::IntegerNode,
+      Prism::FloatNode, Prism::RationalNode, Prism::ImaginaryNode
+    ].freeze
+    private_constant :ALWAYS_TRUTHY_LITERALS
+
     attr_reader :root, :limits
 
     def initialize(root:, limits:)
@@ -174,10 +185,17 @@ module Branchproof
 
       # Boolean expressions nested in an atomic expression (for example, a call
       # argument) are separate decisions when tree_for did not decompose them.
+      fallback_nodes = []
       collected[:phase_two_nodes].each do |node|
         next if inventoried_boolean_nodes[node]
         next if within_defined_expression?(node, defined_ranges) && !node.is_a?(Prism::DefinedNode)
 
+        if fallback_chain?(node)
+          fallback_nodes << node
+          mark_semantic_boolean_nodes(node, inventoried_boolean_nodes)
+          next
+        end
+
         context = if node.is_a?(Prism::MatchPredicateNode)
                     "pattern_in"
                   elsif node.is_a?(Prism::DefinedNode)
@@ -204,9 +222,12 @@ module Branchproof
                        predicate: predicate, context: spec[:context],
                        additional_reasons: spec[:additional_reasons] || [])
       end
-      decisions = boolean_decisions + flow_decisions_for(program, bytes, source_id, file_reasons, encoding,
-                                                         defined_ranges: defined_ranges,
-                                                         nodes: collected[:flow_nodes])
+      fallback_decisions = fallback_nodes.map do |node|
+        build_flow_decision(node, bytes, source_id, file_reasons, encoding)
+      end
+      decisions = boolean_decisions + fallback_decisions +
+                  flow_decisions_for(program, bytes, source_id, file_reasons, encoding,
+                                     defined_ranges: defined_ranges, nodes: collected[:flow_nodes])
       decisions + additional_decisions_for(program, bytes, source_id, file_reasons, encoding,
                                            collected: collected, decisions: decisions)
     end
@@ -410,7 +431,7 @@ module Branchproof
     end
 
     def literal_truth(node)
-      return true if node.is_a?(Prism::TrueNode)
+      return true if ALWAYS_TRUTHY_LITERALS.any? { |type| node.is_a?(type) }
       return false if node.is_a?(Prism::FalseNode) || node.is_a?(Prism::NilNode)
 
       nil