branchproof 0.10.0 → 0.11.0

data/doc/README.md

@@ -107,6 +107,72 @@ files are selected explicitly. The worker prepends the project's `lib` and
 `test` directories (`lib` and `spec` for RSpec) to its child load path, so application `require` calls
 resolve without changing the parent process.
 
+Project defaults can be checked into `.branchproof.json` at the project root:
+
+```json
+{
+  "schema_version": 1,
+  "project": "rails",
+  "framework": "minitest",
+  "sources": ["app/**/*.rb"],
+  "tests": ["test/**/*_test.rb"],
+  "exclude": ["app/generated/**/*.rb"],
+  "minimum": { "mcdc": 80 }
+}
+```
+
+`project` accepts `auto`, `ruby`, or `rails`; `framework` accepts `auto`,
+`minitest`, or `rspec`. `sources` and `tests` replace their corresponding
+defaults, while `exclude` removes matching source files before inventory. A
+configuration file may live elsewhere when passed with `--config PATH`; its
+patterns are still resolved from the project root. Use `--no-config` to disable
+the default file. Command-line project, framework, source, and test selections
+take precedence over the file. Configured `exclude` patterns are applied
+before source inventory and are recorded in run metadata for comparison.
+`--config` and `--no-config` cannot be used together. RSpec configuration
+selectors continue to conflict with an explicit test selection, including one
+supplied by this file.
+
+The `minimum` values are validated percentages from 0 through 100 for the five
+supported criteria: `decision`, `condition`, `condition_decision`, `mcdc`, and
+`decision_table`. A policy is evaluated against the exact numerator and
+denominator counts in the report, so a value such as `66.67` is not rounded
+before it is compared. The policy is recorded in JSON under
+`coverage_policy`.
+
+The command line can add or replace individual policy entries with repeatable
+`--minimum` options. Use `criterion=threshold`, for example:
+
+```sh
+bundle exec branchproof analyze 'lib/**/*.rb' --minimum mcdc=80 \
+  --minimum decision_table=75
+```
+
+CLI values take precedence over matching `minimum` keys from `.branchproof.json`.
+Specifying the same criterion more than once on the command line is an error.
+The five criteria are evaluated independently. A threshold met exactly passes;
+a result below it fails. A requested gate with a zero denominator, unavailable
+coverage, or incomplete observations or analysis is `unavailable`, and exits
+with status 2. A below-threshold gate exits 1. A failed test run makes
+requested policy gates unavailable and exits 2; without a policy, a failed test
+run retains the existing exit status 1. With no policy, the existing report
+exit behavior remains unchanged.
+
+For a Minitest project, a focused configuration can select the library and
+test trees directly:
+
+```json
+{ "schema_version": 1, "framework": "minitest",
+  "sources": ["lib/**/*.rb"], "tests": ["test/**/*_test.rb"] }
+```
+
+For an RSpec project, use its spec patterns instead:
+
+```json
+{ "schema_version": 1, "framework": "rspec",
+  "sources": ["app/**/*.rb"], "tests": ["spec/**/*_spec.rb"] }
+```
+
 Rails analysis boots the application inside the isolated worker after
 Branchproof's loader and the selected framework hooks are installed. The
 application's `rails_helper` owns requiring and configuring `rspec/rails` after
@@ -208,6 +274,15 @@ that did evaluate count toward Condition Coverage even when their value was
 masked by another condition. Here, the two observations prove independence
 for `logged_in?`; `admin?` still needs `[TF] => F`.
 
+This is also a compact test-design walkthrough. A test that records
+`[F-] => F` proves the false branch of `logged_in?`; a test that records
+`[TT] => T` proves the true branch and establishes the current positive path.
+Adding a test that records `[TF] => F` evaluates `admin?` false while
+`logged_in?` stays true, so it supplies the missing independence witness and
+improves the condition, Condition/Decision, MC/DC, and applicable decision-table
+results. The report names the missing vector and its owning test when it is
+observed.
+
 Decision and Condition Coverage are calculated independently from the captured
 evidence. Condition/Decision requires both; MC/DC adds independence evidence.
 Decision Table Coverage is calculated independently of all of them: MC/DC asks
@@ -501,6 +576,34 @@ execution. JSON output always contains the complete evidence document, so an
 explicit view cannot be combined with `--format json`. The `mcdc` executable
 accepts the same arguments for existing scripts.
 
+Terminal reports can be narrowed with `--focus PATH[:LINE]` and bounded with
+`--top N`, where `N` is a positive integer. These options are accepted by
+`analyze` and `report`, and are terminal-only. Focus matches the source spans
+captured in the report; rendering does not reopen or need the original source
+file. `--focus` and `--top` affect displayed detail only: the coverage summary,
+policy gates, diagnostics, exit status, and global counts remain unchanged.
+
+The default view limits decisions. In `--view decision-tables`, the units are
+decision tables; in `--view conditions`, condition and alternative rows; and
+in `--view tests`, test rows. Rows are ordered deterministically by project-
+relative path and source line, with deterministic tie-breakers for each view:
+decisions use column and stable ID; decision tables use decision ID; conditions
+and alternatives use column, decision ID, and condition or alternative index;
+tests use test name and ID. `--top` follows that source order; it does not rank
+rows by risk or coverage. For example:
+
+```sh
+bundle exec branchproof analyze 'lib/**/*.rb' --focus lib/access.rb:12 --top 5
+bundle exec branchproof report .branchproof/current.json --view conditions \
+  --focus lib/access.rb --top 10
+```
+
+Focus and top selections never create a new test run or alter policy scope.
+They also do not generate tests. RSpec rerun labels remain the existing
+recorded selectors and commands. The main finding rows respect the selection;
+supplemental unexecuted, unattributed, and unsupported sections retain their
+run-wide counts rather than expanding into all detail rows.
+
 ### Saved reports and offline comparison
 
 Reports are saved only when requested. Create a local artifact directory and
@@ -518,13 +621,26 @@ The output's parent directory must already exist. Replacing a baseline is an
 explicit `analyze --format json --output` operation; keep CI snapshots as
 artifacts when you need to retain multiple runs.
 
-The `report` command reads the saved document without loading the application
-or running tests. It uses locations and metadata captured in the report, so
-rendering remains useful after the original checkout has moved or been
-removed. New snapshots retain the ladder at every level. Legacy snapshots
-without analysis can still be rendered at Level 1; levels 2 and 3 require
-analysis in the saved report. The repository ignores `.branchproof/`; choose a
-different path and CI artifact policy when a project needs to retain reports.
+The `report` command reads the saved document without loading the application,
+project configuration, or running tests. It uses locations and metadata
+captured in the report, so rendering remains useful after the original
+checkout has moved or been removed. A saved report's policy is inherited by
+default. Repeatable `--minimum criterion=threshold` options override matching
+saved policy entries for that rendering without changing the snapshot file;
+other saved thresholds remain inherited. Offline rendering never consults the
+current `.branchproof.json`.
+
+New live JSON reports use schema `1.4` and include the required
+`coverage_policy` object with the normalized requested minima and recomputed
+gate results. The report validates those results from its exact coverage
+counts rather than trusting a persisted percentage. Readers continue to accept
+schemas `1.0` through `1.3`; an offline policy overlay is optional and
+preserves the input snapshot's schema version, including for legacy reports.
+New snapshots retain the ladder at every level. Legacy snapshots without
+analysis can still be rendered at Level 1; levels 2 and 3 require analysis in
+the saved report.
+The repository ignores `.branchproof/`; choose a different path and CI artifact
+policy when a project needs to retain reports.
 Saved JSON includes existing raw metadata such as test names and expressions;
 relative terminal labels do not mean every legacy JSON field is sanitized.
 
@@ -560,6 +676,29 @@ Invalid input or an incomplete comparison exits 2, which takes
 precedence. Reports are explicit snapshots: comparison never creates history,
 promotes a baseline, or overwrites either input.
 
+### GitHub Actions artifacts
+
+A coverage policy can fail a job while still preserving the report for review.
+Create the output directory before invoking Branchproof and upload the report
+with `if: always()` so failed gates and failed test runs leave an artifact:
+
+```yaml
+- name: Branchproof coverage
+  run: |
+    mkdir -p .branchproof
+    bundle exec branchproof analyze 'lib/**/*.rb' --test 'test/**/*_test.rb' \
+      --format json --output .branchproof/coverage.json \
+      --minimum mcdc=80 --minimum decision_table=75
+
+- name: Upload Branchproof report
+  if: always()
+  uses: actions/upload-artifact@v4
+  with:
+    name: branchproof-coverage
+    path: .branchproof/coverage.json
+    if-no-files-found: warn
+```
+
 MC/DC has two related questions. Evaluation asks whether a condition was
 observed with a value, including short-circuiting. Independent proof asks
 whether the analyzer found a pair of observations where that condition changes
@@ -670,8 +809,8 @@ Ruby-defined custom `!` methods keep their runtime behavior;
 evidence that contradicts Boolean negation is rejected instead of proving
 coverage with an invalid logical model.
 
-New reports use schema `1.3`; saved schema `1.0`, `1.1`, and `1.2` reports
-remain readable. Comparison distinguishes decision-table coverage movement
+New reports use schema `1.4`; saved schema `1.0`, `1.1`, `1.2`, and `1.3`
+reports remain readable. Comparison distinguishes decision-table coverage movement
 (`rule coverage gained`, `rule coverage lost`) from analysis movement
 (`rule reachability changed`), and treats a structurally changed decision as a
 changed decision-table context instead of guessing which old rule a new rule
@@ -730,7 +869,11 @@ namespace. The CLI is the supported way to run a complete analysis;
 child-environment policy,
 and `Branchproof::RailsSupport` is the optional Rails boot boundary. The library
 classes expose the source, runtime, evidence, analysis, and report contracts
-for adapters and integrations.
+for adapters and integrations. `Branchproof::CoveragePolicy#call` evaluates a
+normalized `minimum` hash against a report document. `Report#coverage_policy`
+returns the recomputed policy record, and `Report#coverage_policy_lines`
+returns its terminal lines; both are available to integrations that need the
+same gate result as the CLI.
 
 ## Development
 

data/lib/branchproof/cli.rb

@@ -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
@@ -94,10 +95,13 @@ module Branchproof
       @stdout.write(<<~HELP)
         Usage:
           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]
-            [--format terminal|json] [--output PATH] [--limits PATH] [--no-reachability] [-- RUNNER_ARGS]
+            [--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
 
@@ -211,11 +225,18 @@ module Branchproof
       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: 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]
       }
+      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
@@ -231,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"
 
@@ -240,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, project_mode: "auto", framework: "auto", explicit_tests: false }
+                  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
@@ -249,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"
@@ -272,9 +307,20 @@ module Branchproof
         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"
           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[:config_disabled] = true
         when "--limits"
           limits_path = args.shift
           raise ArgumentError, "--limits requires a readable JSON path" unless limits_path && File.file?(limits_path)
@@ -286,10 +332,36 @@ 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: Dir.pwd, mode: options[:project_mode], framework: options[:framework]).to_h
+      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
@@ -302,7 +374,34 @@ module Branchproof
       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
@@ -313,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)

data/lib/branchproof/comparison.rb

@@ -8,7 +8,7 @@ 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:)
@@ -481,6 +481,7 @@ 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
 
@@ -517,6 +518,10 @@ module Branchproof
       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