branchproof 0.9.0 → 0.11.0

data/lib/branchproof/cli.rb

@@ -33,10 +33,10 @@ module Branchproof
 
       inventory = build_inventory(options)
       evidence = empty_evidence(inventory, options)
-      baseline = if options[:tests].empty?
-                   { status: "INCOMPLETE", executed_tests: 0, failed_tests: 0, skipped_tests: 0, finalized: false }
-                 else
+      baseline = if run_worker?(options)
                    run_worker(options, inventory, evidence)
+                 else
+                   { status: "INCOMPLETE", executed_tests: 0, failed_tests: 0, skipped_tests: 0, finalized: false }
                  end
       if value(baseline, :evidence)
         merge_status = evidence.merge(snapshot: value(baseline, :evidence))
@@ -77,7 +77,8 @@ module Branchproof
       report = Report.new(inventory: inventory, evidence: value(baseline, :evidence) || snapshot,
                           analysis: analysis, minima: minima, baseline: baseline, diagnostics: diagnostics,
                           level: options[:level], missing_only: options[:missing_only], view: options[:view],
-                          run_metadata: run_metadata(options, baseline))
+                          run_metadata: run_metadata(options, baseline), minimum: options[:minimum],
+                          focus: options[:focus], top: options[:top])
       output_report(report, options)
       report.exit_code
     rescue ArgumentError => e
@@ -93,11 +94,14 @@ module Branchproof
     def help
       @stdout.write(<<~HELP)
         Usage:
-          branchproof analyze [SOURCE_GLOB ...] [--test TEST_GLOB] [--project auto|ruby|rails]
-            [--view decisions|conditions|tests|decision-tables] [--level 1|2|3] [--missing-only]
-            [--format terminal|json] [--output PATH] [--limits PATH] [--no-reachability] [-- RUNNER_ARGS]
+          branchproof analyze [SOURCE_GLOB ...] [--test TEST_GLOB] [--project auto|ruby|rails] [--framework auto|minitest|rspec]
+            [--view decisions|conditions|tests|decision-tables] [--level 1|2|3] [--missing-only] [--minimum CRITERION=THRESHOLD]
+            [--focus PATH[:LINE]] [--top N]
+            [--format terminal|json] [--output PATH] [--limits PATH] [--config PATH|--no-config]
+            [--no-reachability] [-- RUNNER_ARGS]
           branchproof report SNAPSHOT [--view decisions|conditions|tests|decision-tables]
-            [--level 1|2|3] [--missing-only] [--format terminal|json] [--output PATH]
+            [--level 1|2|3] [--missing-only] [--minimum CRITERION=THRESHOLD] [--focus PATH[:LINE]] [--top N]
+            [--format terminal|json] [--output PATH]
           branchproof compare BEFORE AFTER [--format terminal|json] [--output PATH] [--fail-on-regression]
         mcdc accepts the same commands as a compatibility alias.
         JSON always contains full evidence; --view requires terminal output.
@@ -142,14 +146,15 @@ module Branchproof
         end
 
         report = Report.from_document(document: document, level: options[:level], view: options[:view],
-                                      missing_only: options[:missing_only])
+                                      missing_only: options[:missing_only], minimum: options[:minimum_overrides],
+                                      focus: options[:focus], top: options[:top])
         output_report(report, options)
         report.exit_code
       end
     end
 
     def parse_offline(command, args)
-      options = { format: :terminal, view: :decisions, missing_only: false }
+      options = { format: :terminal, view: :decisions, missing_only: false, minimum_overrides: {} }
       paths = []
       until args.empty?
         token = args.shift
@@ -166,7 +171,7 @@ module Branchproof
           raise ArgumentError, "--fail-on-regression requires compare" unless command == "compare"
 
           options[:fail_on_regression] = true
-        when "--view", "--level", "--missing-only"
+        when "--view", "--level", "--missing-only", "--minimum", "--focus", "--top"
           raise ArgumentError, "#{token} requires report" unless command == "report"
 
           case token
@@ -176,6 +181,14 @@ module Branchproof
           when "--level"
             options[:level] = Integer(args.shift.to_s, 10)
             raise ArgumentError, "level must be 1, 2, or 3" unless (1..3).cover?(options[:level])
+          when "--minimum"
+            add_minimum_override!(options, args.shift)
+          when "--focus"
+            options[:focus] = args.shift
+            raise ArgumentError, "--focus requires PATH or PATH:LINE" if options[:focus].nil? || options[:focus].start_with?("-")
+          when "--top"
+            options[:top] = args.shift
+            raise ArgumentError, "--top requires a positive integer" if options[:top].nil?
           else options[:missing_only] = true
           end
         else
@@ -188,6 +201,7 @@ module Branchproof
       raise ArgumentError, "#{command} requires #{expected} saved report #{expected == 1 ? "path" : "paths"}" unless paths.length == expected
 
       validate_view!(options)
+      validate_selection!(options)
       [options, paths]
     end
 
@@ -205,12 +219,31 @@ module Branchproof
         source = value(test, :source) || {}
         [value(test, :id), { relative_path: relative_path(value(source, :path), root), line: value(source, :line) }]
       end
-      { captured_at: Time.now.utc.iso8601, requested_level: options[:level], project_kind: options[:project][:kind],
+      project_metadata = value(baseline, :project) || options[:project]
+      selected_test_files = value(baseline, :selected_test_files)
+      test_files = selected_test_files || options[:tests]
+      metadata = {
+        captured_at: Time.now.utc.iso8601, requested_level: options[:level], project_kind: options[:project][:kind],
         project_root: root, source_patterns: options[:source_patterns].map { |path| relative_path(path, root) },
+        exclude_patterns: Array(options[:exclude]).map { |path| relative_pattern(path, root) },
         test_patterns: options[:test_patterns].map { |path| relative_path(path, root) },
-        test_files: options[:tests].map { |path| relative_path(path, root) }, runner_args: options[:runner_args],
+        test_files: Array(test_files).map { |path| relative_path(path, root) }, runner_args: options[:runner_args],
         seed: value(baseline, :seed), limits: options[:limits], test_locations: locations,
-        reachability: options[:reachability] }
+        reachability: options[:reachability]
+      }
+      if options[:configuration]
+        metadata[:excluded_files] = Array(options[:excluded_files]).map { |path| relative_path(path, root) }
+        metadata[:selected_source_files] = Array(options[:selected_source_files]).map do |path|
+          relative_path(path, root)
+        end
+      end
+      %i[selected_test_files selected_example_ids].each do |key|
+        metadata[key] = value(baseline, key) if value(baseline, key)
+      end
+      %i[framework framework_version rspec_rails_version rails_version].each do |key|
+        metadata[key] = value(project_metadata, key) if value(project_metadata, key)
+      end
+      metadata
     end
 
     def relative_path(path, root)
@@ -219,6 +252,10 @@ module Branchproof
       Pathname.new(File.expand_path(path, root)).relative_path_from(Pathname.new(root)).to_s
     end
 
+    def relative_pattern(path, root)
+      path.to_s.empty? ? path.to_s : relative_path(path, root)
+    end
+
     def parse(argv)
       return nil if argv.empty? || argv.first != "analyze"
 
@@ -228,7 +265,9 @@ module Branchproof
       args = args[0...delimiter] if delimiter
       options = { level: 3, format: :terminal, output: nil, tests: [], source_paths: [], limits: Limits.default,
                   runner_args: runner_args, project: nil, missing_only: false, view: :decisions,
-                  reachability: true }
+                  reachability: true, project_mode: "auto", framework: "auto", explicit_tests: false,
+                  explicit_project: false, explicit_framework: false, explicit_sources: false,
+                  config_path: nil, config_disabled: false, minimum_overrides: {} }
       until args.empty?
         token = args.shift
         case token
@@ -237,6 +276,14 @@ module Branchproof
           options[:explicit_view] = true
         when "--missing-only"
           options[:missing_only] = true
+        when "--minimum"
+          add_minimum_override!(options, args.shift)
+        when "--focus"
+          options[:focus] = args.shift
+          raise ArgumentError, "--focus requires PATH or PATH:LINE" if options[:focus].nil? || options[:focus].start_with?("-")
+        when "--top"
+          options[:top] = args.shift
+          raise ArgumentError, "--top requires a positive integer" if options[:top].nil?
         when "--no-reachability"
           options[:reachability] = false
         when "--level"
@@ -255,11 +302,25 @@ module Branchproof
         when "--test"
           options[:tests] << args.shift
           raise ArgumentError, "--test requires a glob" if options[:tests].last.nil? || options[:tests].last.empty?
+
+          options[:explicit_tests] = true
+        when "--framework"
+          options[:framework] = args.shift
+          raise ArgumentError, "--framework requires auto, minitest, or rspec" if options[:framework].nil? || options[:framework].empty?
+
+          options[:explicit_framework] = true
         when "--project"
-          mode = args.shift
-          raise ArgumentError, "--project requires auto, ruby, or rails" if mode.nil? || mode.empty?
+          options[:project_mode] = args.shift
+          raise ArgumentError, "--project requires auto, ruby, or rails" if options[:project_mode].nil? || options[:project_mode].empty?
+
+          options[:explicit_project] = true
+        when "--config"
+          options[:config_path] = args.shift
+          raise ArgumentError, "--config requires a readable JSON path" if options[:config_path].nil? || options[:config_path].empty?
+        when "--no-config"
+          raise ArgumentError, "--config and --no-config are mutually exclusive" if options[:config_path]
 
-          options[:project] = Project.new(root: Dir.pwd, mode: mode).to_h
+          options[:config_disabled] = true
         when "--limits"
           limits_path = args.shift
           raise ArgumentError, "--limits requires a readable JSON path" unless limits_path && File.file?(limits_path)
@@ -271,23 +332,76 @@ module Branchproof
           raise ArgumentError, "unknown option: #{token}" if token.start_with?("-")
 
           options[:source_paths] << token
+          options[:explicit_sources] = true
         end
       end
+      root = Dir.pwd
+      if options[:config_path] && options[:config_disabled]
+        raise ArgumentError, "--config and --no-config are mutually exclusive"
+      end
+
+      configuration = Configuration.load(path: options[:config_path] || ".branchproof.json", root: root,
+                                         explicit: !options[:config_path].nil?, disabled: options[:config_disabled])
+      options[:configuration] = configuration
+      if configuration
+        options[:project_mode] = configuration[:project] if !options[:explicit_project] && configuration.key?(:project)
+        options[:framework] = configuration[:framework] if !options[:explicit_framework] && configuration.key?(:framework)
+        if !options[:explicit_sources] && configuration.key?(:sources)
+          options[:source_paths] = configuration[:sources].dup
+        end
+        if !options[:explicit_tests] && configuration.key?(:tests)
+          options[:tests] = configuration[:tests].dup
+          options[:explicit_tests] = true
+        end
+        options[:exclude] = Array(configuration[:exclude]).dup
+        options[:minimum] = configuration.fetch(:minimum, {}).dup.merge(options[:minimum_overrides])
+      else
+        options[:exclude] = []
+        options[:minimum] = options[:minimum_overrides].dup
+      end
+      options[:project] = Project.new(root: root, mode: options[:project_mode], framework: options[:framework]).to_h
       validate_view!(options)
+      validate_selection!(options)
       if options[:missing_only] && (options[:format] != :terminal || options[:level] == 1)
         raise ArgumentError, "--missing-only requires terminal format and level 2 or 3"
       end
 
-      options[:project] ||= Project.new(root: Dir.pwd, mode: "auto").to_h
       options[:source_paths] = default_sources if options[:source_paths].empty?
-      options[:tests] = default_tests if options[:tests].empty?
+      options[:tests] = default_tests(options[:project]) if options[:tests].empty?
       options[:source_patterns] = options[:source_paths].dup
-      options[:test_patterns] = argv.include?("--test") ? options[:tests].dup : %w[test/**/*_test.rb test/**/test_*.rb]
+      options[:test_patterns] = options[:explicit_tests] ? options[:tests].dup : options[:project][:test_patterns]
       options[:tests] = expand_paths(options[:tests], root: options[:project][:root])
       options
     end
 
+    def add_minimum_override!(options, argument)
+      text = argument.to_s
+      match = text.match(/\A([a-z_]+)=([0-9]+(?:\.[0-9]+)?)\z/)
+      raise ArgumentError, "minimum must be CRITERION=THRESHOLD" unless match
+
+      criterion = match[1]
+      threshold_text = match[2]
+      threshold = threshold_text.include?(".") ? Float(threshold_text) : Integer(threshold_text, 10)
+      normalized = CoveragePolicy.normalize(criterion => threshold)
+      criterion = normalized.keys.first
+      raise ArgumentError, "duplicate coverage criterion: #{criterion}" if options[:minimum_overrides].key?(criterion)
+
+      options[:minimum_overrides][criterion] = normalized.fetch(criterion)
+    rescue ArgumentError
+      raise
+    rescue TypeError
+      raise ArgumentError, "minimum threshold must be a finite number from 0 to 100"
+    end
+
+    def validate_selection!(options)
+      return unless options[:focus] || options[:top]
+      raise ArgumentError, "focus and top filters are terminal-only" if options[:format] == :json
+
+      ReportSelection.new(focus: options[:focus], top: options[:top])
+    end
+
     def build_inventory(options)
+      root = options[:project][:root]
       test_paths = options[:tests].filter_map do |path|
         File.realpath(path)
       rescue StandardError
@@ -298,13 +412,21 @@ module Branchproof
       rescue StandardError
         nil
       end
-      selected = expand_paths(options[:source_paths]).reject do |path|
-        relative = Pathname.new(path).relative_path_from(Pathname.new(Dir.pwd)).to_s
+      excluded = expand_paths(Array(options[:exclude]).reject(&:empty?), root: root)
+      excluded_paths = excluded.filter_map do |path|
+        File.realpath(path)
+      rescue StandardError
+        nil
+      end
+      selected = expand_paths(options[:source_paths], root: root).reject do |path|
+        relative = Pathname.new(path).relative_path_from(Pathname.new(root)).to_s
         canonical = File.realpath(path)
         relative.match?(%r{\A(?:test|spec|tool|vendor)(?:/|\z)}) ||
-          test_paths.include?(canonical) || loaded_paths.include?(canonical)
+          test_paths.include?(canonical) || loaded_paths.include?(canonical) || excluded_paths.include?(canonical)
       end
-      Source.new(root: Dir.pwd, limits: options[:limits]).inventory(paths: selected)
+      options[:excluded_files] = excluded
+      options[:selected_source_files] = selected
+      Source.new(root: root, limits: options[:limits]).inventory(paths: selected)
     end
 
     def empty_evidence(inventory, options)
@@ -315,18 +437,10 @@ module Branchproof
       begin
         directory = Dir.mktmpdir("branchproof-run-")
         config = File.join(directory, "request.json")
-        payload = {
-          inventory: inventory, limits: options[:limits], run_id: evidence.run_id,
-          test_files: options[:tests], runner_args: options[:runner_args], project: options[:project],
-          result_path: File.join(directory, "result.json"), marker_path: File.join(directory, "complete.marker")
-        }
+        payload = worker_payload(options, inventory, evidence, directory)
         File.binwrite(config, JSON.generate(normalize(payload)))
         script = "require 'branchproof'; exit(Branchproof::Worker.child_process(ARGV.fetch(0)).to_i)"
-        child_stdout, stderr, child_status = Open3.capture3(options[:project][:environment], RbConfig.ruby, "-I",
-                                                            File.expand_path("..", __dir__), "-e", script, config,
-                                                            chdir: options[:project][:root])
-        @stderr.write(child_stdout) unless child_stdout.to_s.empty?
-        @stderr.write(stderr) unless stderr.to_s.empty?
+        stderr, child_status = stream_worker(options, script, config)
         unless File.file?(payload[:marker_path]) && File.file?(payload[:result_path])
           return { status: "ERROR", executed_tests: 0, failed_tests: 0, skipped_tests: 0, finalized: false,
                    diagnostics: [{ code: "worker_incomplete", severity: "error", message: stderr.to_s.strip }] }
@@ -346,6 +460,30 @@ module Branchproof
         diagnostics: [{ code: "runner", severity: "error", message: e.message }] }
     end
 
+    def stream_worker(options, script, config)
+      diagnostic_output = +""
+      Open3.popen3(options[:project][:environment], RbConfig.ruby, "-I",
+                   File.expand_path("..", __dir__), "-e", script, config,
+                   chdir: options[:project][:root]) do |input, output, errors, child|
+        input.close
+        streams = [output, errors]
+        until streams.empty?
+          IO.select(streams).first.each do |stream|
+            chunk = stream.read_nonblock(16_384, exception: false)
+            if chunk.nil?
+              streams.delete(stream)
+            elsif chunk != :wait_readable
+              @stderr.write(chunk)
+              @stderr.flush if @stderr.respond_to?(:flush)
+              diagnostic_output << chunk
+              diagnostic_output = diagnostic_output.byteslice(-16_384, 16_384) if diagnostic_output.bytesize > 16_384
+            end
+          end
+        end
+        [diagnostic_output, child.value]
+      end
+    end
+
     def output_report(report, options)
       created = false
       if options[:output]
@@ -362,6 +500,19 @@ module Branchproof
       File.unlink(temporary) if created && temporary && File.file?(temporary)
     end
 
+    def run_worker?(options)
+      !options[:tests].empty? || options[:project][:framework].to_s == "rspec"
+    end
+
+    def worker_payload(options, inventory, evidence, directory)
+      {
+        inventory: inventory, limits: options[:limits], run_id: evidence.run_id,
+        test_files: options[:tests], runner_args: options[:runner_args], project: options[:project],
+        test_selection_explicit: options[:explicit_tests],
+        result_path: File.join(directory, "result.json"), marker_path: File.join(directory, "complete.marker")
+      }
+    end
+
     def report_string(report, format)
       buffer = StringIO.new
       report.write(io: buffer, format: format)
@@ -377,8 +528,9 @@ module Branchproof
       %w[lib/**/*.rb app/**/*.rb]
     end
 
-    def default_tests
-      candidates = Dir.glob("test/**/*_test.rb", base: Dir.pwd) + Dir.glob("test/**/test_*.rb", base: Dir.pwd)
+    def default_tests(project = nil)
+      project ||= Project.new(root: Dir.pwd, mode: "auto", framework: "auto").to_h
+      candidates = Array(project[:test_patterns]).flat_map { |pattern| Dir.glob(pattern, base: project[:root]) }
       candidates.map! { |path| File.expand_path(path, Dir.pwd) }
       candidates.reject { |path| default_test_excluded?(path) }.uniq.sort
     end
@@ -387,7 +539,8 @@ module Branchproof
       relative = Pathname.new(path).relative_path_from(Pathname.new(Dir.pwd)).to_s
       segments = relative.split(File::SEPARATOR)
       basename = File.basename(path)
-      basename == "test_helper.rb" || segments.include?("support") || segments.include?("fixtures")
+      %w[test_helper.rb spec_helper.rb rails_helper.rb].include?(basename) ||
+        segments.include?("support") || segments.include?("fixtures")
     end
 
     def expand_paths(paths, root: Dir.pwd)

data/lib/branchproof/comparison.rb

@@ -2,12 +2,13 @@
 
 # rubocop:disable Metrics/ClassLength, Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
 require "json"
+require "pathname"
 
 module Branchproof
   # Compares two complete report documents without loading or executing the project.
   class Comparison
     SCHEMA_VERSION = "1.0"
-    SUPPORTED_REPORT_SCHEMAS = %w[1.0 1.1 1.2 1.3].freeze
+    SUPPORTED_REPORT_SCHEMAS = %w[1.0 1.1 1.2 1.3 1.4].freeze
     CRITERION_VERSION = "masking_occurrence_v1"
 
     def initialize(before:, after:)
@@ -369,9 +370,17 @@ module Branchproof
         tests = Array(value(value(document, :observations), :tests)).to_h { |test| [value(test, :id).to_s, test] }
         rows = index.tests.to_h { |test| [test[:id].to_s, test] }
         keys = tests.to_h do |id, test|
-          parts = %i[adapter class_name method_name].map { |key| value(test, key) }
-          parts << rows.dig(id, :relative_path)
-          [id, parts.all? { |part| part.is_a?(String) && !part.empty? } ? parts : nil]
+          adapter = value(test, :adapter).to_s
+          path = rows.dig(id, :relative_path)
+          key = if adapter.downcase == "rspec"
+                  example_id = value(test, :example_id).to_s
+                  # Scoped IDs are positional selectors, valid only within the same spec revision.
+                  [adapter, rspec_example_path(document, example_id) || path, rspec_scope(example_id),
+                   value(test, :name), path, value(test, :spec_digest), value(test, :source_digest)]
+                else
+                  [adapter, value(test, :class_name), value(test, :method_name), path]
+                end
+          [id, key.all? { |part| part.is_a?(String) && !part.empty? } ? key : nil]
         end
         results = Array(value(value(document, :analysis), :decisions)).flat_map do |decision|
           Array(value(decision, :condition_results))
@@ -447,6 +456,13 @@ module Branchproof
       if context(@before)[:test_keys].values.sort_by(&:to_s) != context(@after)[:test_keys].values.sort_by(&:to_s)
         changes << "test population differs"
       end
+      if [@before, @after].any? do |document|
+        context(document)[:tests].any? do |id, test|
+          value(test, :adapter).to_s.downcase == "rspec" && context(document)[:test_keys][id].nil?
+        end
+      end
+        changes << "RSpec example identity is uncertain: missing spec revision or selector evidence"
+      end
       changes << "Deltas describe observed runs; nondeterminism and external environment changes are not ruled out."
       changes
     end
@@ -454,9 +470,10 @@ module Branchproof
     def comparability_reasons(changed_paths)
       reasons = []
       reasons << "source files changed: #{changed_paths.sort.join(", ")}" unless changed_paths.empty?
-      %i[project_kind runner_args source_patterns test_patterns limits runtime].each do |key|
-        left = metadata(@before, key)
-        right = metadata(@after, key)
+      %i[project_kind framework framework_version rspec_rails_version runner_args source_patterns test_patterns limits
+         runtime].each do |key|
+        left = key == :framework ? comparison_framework(@before) : metadata(@before, key)
+        right = key == :framework ? comparison_framework(@after) : metadata(@after, key)
         if key == :runner_args
           left = comparable_runner_args(left)
           right = comparable_runner_args(right)
@@ -464,13 +481,47 @@ module Branchproof
         reasons << "#{key} differs" if !left.nil? && !right.nil? && left != right
       end
       reasons << "source selection differs" if source_selection(@before) != source_selection(@after)
+      reasons << "source exclusion scope differs" if exclusion_scope(@before) != exclusion_scope(@after)
       reasons
     end
 
+    def comparison_framework(document)
+      explicit = metadata(document, :framework)
+      return explicit unless explicit.nil? || explicit.to_s.empty?
+
+      adapters = Array(value(value(document, :observations), :tests)).filter_map do |test|
+        adapter = value(test, :adapter).to_s.downcase
+        adapter unless adapter.empty? || adapter == "unknown"
+      end.uniq
+      adapters.length == 1 ? adapters.first : nil
+    end
+
+    def rspec_scope(example_id)
+      match = example_id.to_s.match(/(\[[^\]]+\])\z/)
+      match && match[1]
+    end
+
+    def rspec_example_path(document, example_id)
+      path = example_id.to_s.sub(/\[[^\]]+\]\z/, "")
+      return nil if path.empty?
+      return path.sub(%r{\A\./}, "") unless path.start_with?("/")
+
+      root = value(value(document, :source_inventory), :root) || metadata(document, :project_root)
+      return nil unless root
+
+      Pathname.new(path).relative_path_from(Pathname.new(root.to_s)).to_s
+    rescue ArgumentError
+      nil
+    end
+
     def source_selection(document)
       value(value(document, :run_metadata), :source_patterns)
     end
 
+    def exclusion_scope(document)
+      Array(value(value(document, :run_metadata), :exclude_patterns))
+    end
+
     def metadata_requirements
       [@before, @after].each_with_index.filter_map do |document, index|
         metadata = value(document, :run_metadata)

data/lib/branchproof/configuration.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "coverage_policy"
+
+module Branchproof
+  # Loads and validates the project-local .branchproof.json policy.
+  class Configuration
+    SCHEMA_VERSION = 1
+    PROJECTS = %w[auto ruby rails].freeze
+    FRAMEWORKS = %w[auto minitest rspec].freeze
+    MINIMUM_CRITERIA = CoveragePolicy::CRITERIA.keys.freeze
+    FIELDS = %w[schema_version project framework sources tests exclude minimum].freeze
+
+    class << self
+      def load(path:, root:, explicit: false, disabled: false)
+        return nil if disabled
+
+        root = File.expand_path(root)
+        path = File.expand_path(path, root)
+        return nil unless ensure_file!(path, explicit)
+
+        payload = read_payload(path)
+        validate(payload, path: path, root: root)
+      end
+
+      private
+
+      def ensure_file!(path, explicit)
+        unless File.exist?(path)
+          return nil unless explicit
+
+          raise ArgumentError, "configuration file does not exist: #{path}"
+        end
+        return true if File.file?(path)
+
+        raise ArgumentError, "configuration path is not a file: #{path}"
+      end
+
+      def read_payload(path)
+        JSON.parse(File.binread(path))
+      rescue JSON::ParserError => e
+        raise ArgumentError, "invalid JSON configuration: #{e.message}"
+      rescue SystemCallError => e
+        raise ArgumentError, "configuration could not be read: #{e.message}"
+      end
+
+      def validate(payload, path:, root:)
+        validate_shape!(payload)
+        validate_values!(payload)
+
+        payload.each_with_object({ schema_version: SCHEMA_VERSION, path: path, root: root }) do |(key, value), result|
+          next if key == "schema_version"
+
+          result[key.to_sym] = key == "minimum" ? value.transform_keys(&:to_s) : value
+        end
+      end
+
+      def validate_shape!(payload)
+        raise ArgumentError, "configuration must be a JSON object" unless payload.is_a?(Hash)
+
+        unknown = payload.keys - FIELDS
+        return if unknown.empty? && valid_schema_version?(payload["schema_version"])
+
+        raise ArgumentError, "configuration has unknown fields: #{unknown.join(", ")}" unless unknown.empty?
+
+        raise ArgumentError, "configuration schema_version must be #{SCHEMA_VERSION}"
+      end
+
+      def valid_schema_version?(value)
+        value.is_a?(Integer) && value == SCHEMA_VERSION
+      end
+
+      def validate_values!(payload)
+        validate_enum(payload, "project", PROJECTS)
+        validate_enum(payload, "framework", FRAMEWORKS)
+        %w[sources tests].each { |field| validate_nonempty_strings(payload, field) if payload.key?(field) }
+        validate_strings(payload, "exclude") if payload.key?("exclude")
+        validate_minimum(payload["minimum"]) if payload.key?("minimum")
+      end
+
+      def validate_enum(payload, field, values)
+        return unless payload.key?(field)
+
+        value = payload[field]
+        raise ArgumentError, "configuration #{field} must be a string" unless value.is_a?(String)
+        raise ArgumentError, "configuration #{field} must be #{values.join(", ")}" unless values.include?(value)
+      end
+
+      def validate_nonempty_strings(payload, field)
+        value = payload[field]
+        valid = value.is_a?(Array) && !value.empty? && value.all? { |item| item.is_a?(String) && !item.empty? }
+        raise ArgumentError, "configuration #{field} must be a nonempty array of strings" unless valid
+      end
+
+      def validate_strings(payload, field)
+        value = payload[field]
+        valid = value.is_a?(Array) && value.all? { |item| item.is_a?(String) && !item.empty? }
+        raise ArgumentError, "configuration #{field} must be an array of strings" unless valid
+      end
+
+      def validate_minimum(value)
+        raise ArgumentError, "configuration minimum must be an object" unless value.is_a?(Hash)
+
+        CoveragePolicy.normalize(value)
+      rescue ArgumentError => e
+        raise ArgumentError, "configuration minimum #{e.message.sub(/\Acoverage minimum for /, "")}"
+      end
+    end
+  end
+end