polyrun 1.0.0

data/lib/polyrun/cli/run_shards_planning.rb

@@ -0,0 +1,124 @@
+require_relative "run_shards_plan_options"
+require_relative "run_shards_plan_boot_phases"
+
+module Polyrun
+  class CLI
+    # Parses argv, loads config, builds {Partition::Plan} for run-shards.
+    module RunShardsPlanning
+      include RunShardsPlanOptions
+      include RunShardsPlanBootPhases
+
+      private
+
+      # @return [Array(Integer, Hash, nil)] [exit_code, nil] on failure, or [nil, ctx] on success
+      def run_shards_build_plan(argv, config_path)
+        boot = run_shards_plan_boot(argv, config_path)
+        return boot if boot.size == 2
+
+        run_t0, head, cmd, cfg, pc = boot
+        phase = run_shards_plan_phase_a(head, cmd, pc)
+        return [phase[1], nil] if phase[0] == :fail
+
+        _tag, o, cmd = phase
+        run_shards_plan_phase_b(o, cmd, cfg, pc, run_t0, config_path)
+      end
+
+      def run_shards_default_timing_path(pc, timing_path, strategy)
+        return timing_path if timing_path
+
+        tf = pc["timing_file"] || pc[:timing_file]
+        return tf if tf && (Polyrun::Partition::Plan.cost_strategy?(strategy) || Polyrun::Partition::Plan.hrw_strategy?(strategy))
+
+        nil
+      end
+
+      def run_shards_validate_workers!(o)
+        w = o[:workers]
+        if w < 1
+          Polyrun::Log.warn "polyrun run-shards: --workers must be >= 1"
+          return 2
+        end
+        if w > RunShardsCommand::MAX_PARALLEL_WORKERS
+          Polyrun::Log.warn "polyrun run-shards: capping --workers / POLYRUN_WORKERS from #{w} to #{RunShardsCommand::MAX_PARALLEL_WORKERS}"
+          o[:workers] = RunShardsCommand::MAX_PARALLEL_WORKERS
+        end
+        nil
+      end
+
+      def run_shards_validate_cmd(cmd)
+        if cmd.empty?
+          Polyrun::Log.warn "polyrun run-shards: empty command after --"
+          return 2
+        end
+        nil
+      end
+
+      def run_shards_resolve_items(paths_file)
+        resolved = Polyrun::Partition::Paths.resolve_run_shard_items(paths_file: paths_file)
+        if resolved[:error]
+          Polyrun::Log.warn "polyrun run-shards: #{resolved[:error]}"
+          return [nil, nil, 2]
+        end
+        items = resolved[:items]
+        paths_source = resolved[:source]
+        Polyrun::Log.warn "polyrun run-shards: #{items.size} spec path(s) from #{paths_source}"
+
+        if items.empty?
+          Polyrun::Log.warn "polyrun run-shards: no spec paths (spec/spec_paths.txt, partition.paths_file, or spec/**/*_spec.rb)"
+          return [nil, nil, 2]
+        end
+        [items, paths_source, nil]
+      end
+
+      def run_shards_resolve_costs(timing_path, strategy)
+        if timing_path
+          costs = Polyrun::Partition::Plan.load_timing_costs(File.expand_path(timing_path.to_s, Dir.pwd))
+          if costs.empty?
+            Polyrun::Log.warn "polyrun run-shards: timing file missing or empty: #{timing_path}"
+            return [nil, nil, 2]
+          end
+          unless Polyrun::Partition::Plan.cost_strategy?(strategy) || Polyrun::Partition::Plan.hrw_strategy?(strategy)
+            Polyrun::Log.warn "polyrun run-shards: using cost_binpack (timing data present)" if @verbose
+            strategy = "cost_binpack"
+          end
+          [costs, strategy, nil]
+        elsif Polyrun::Partition::Plan.cost_strategy?(strategy)
+          Polyrun::Log.warn "polyrun run-shards: --timing or partition.timing_file required for strategy #{strategy}"
+          [nil, nil, 2]
+        else
+          [nil, strategy, nil]
+        end
+      end
+
+      def run_shards_make_plan(items, workers, strategy, seed, costs, constraints)
+        Polyrun::Debug.time("Partition::Plan.new (partition #{items.size} paths → #{workers} shards)") do
+          Polyrun::Partition::Plan.new(
+            items: items,
+            total_shards: workers,
+            strategy: strategy,
+            seed: seed,
+            costs: costs,
+            constraints: constraints,
+            root: Dir.pwd
+          )
+        end
+      end
+
+      def run_shards_debug_shard_sizes(plan, workers)
+        return unless Polyrun::Debug.enabled?
+
+        workers.times do |s|
+          n = plan.shard(s).size
+          Polyrun::Debug.log("run-shards: shard #{s} → #{n} spec file(s)")
+        end
+      end
+
+      def run_shards_warn_parallel_banner(item_count, workers, strategy)
+        Polyrun::Log.warn <<~MSG
+          polyrun run-shards: #{item_count} spec path(s) -> #{workers} parallel worker processes (not Ruby threads); strategy=#{strategy}
+          (plain `bundle exec rspec` is one process; this command fans out.)
+        MSG
+      end
+    end
+  end
+end

data/lib/polyrun/cli/run_shards_run.rb

@@ -0,0 +1,168 @@
+require "shellwords"
+require "rbconfig"
+
+require_relative "run_shards_planning"
+
+module Polyrun
+  class CLI
+    # Partition + spawn workers for `polyrun run-shards` (keeps {RunShardsCommand} file small).
+    module RunShardsRun
+      include RunShardsPlanning
+
+      private
+
+      def run_shards_run!(argv, config_path)
+        code, ctx = run_shards_build_plan(argv, config_path)
+        return code if code
+
+        run_shards_workers_and_merge(ctx)
+      end
+
+      def run_shards_workers_and_merge(ctx)
+        pids = run_shards_spawn_workers(ctx)
+        return 1 if pids.empty?
+
+        run_shards_warn_interleaved(ctx[:parallel], pids.size)
+
+        shard_results = run_shards_wait_all_children(pids)
+        failed = shard_results.reject { |r| r[:success] }.map { |r| r[:shard] }
+
+        Polyrun::Debug.log(format(
+          "run-shards: workers wall time since start: %.3fs",
+          Process.clock_gettime(Process::CLOCK_MONOTONIC) - ctx[:run_t0]
+        ))
+
+        if ctx[:parallel]
+          Polyrun::Log.warn "polyrun run-shards: finished #{pids.size} worker(s)" + (failed.any? ? " (some failed)" : " (exit 0)")
+        end
+
+        if failed.any?
+          run_shards_log_failed_reruns(failed, shard_results, ctx[:plan], ctx[:parallel], ctx[:workers], ctx[:cmd])
+          return 1
+        end
+
+        run_shards_merge_or_hint_coverage(ctx)
+      end
+
+      def run_shards_spawn_workers(ctx)
+        workers = ctx[:workers]
+        cmd = ctx[:cmd]
+        cfg = ctx[:cfg]
+        plan = ctx[:plan]
+        parallel = ctx[:parallel]
+
+        pids = []
+        workers.times do |shard|
+          paths = plan.shard(shard)
+          if paths.empty?
+            Polyrun::Log.warn "polyrun run-shards: shard #{shard} skipped (no paths)" if @verbose || parallel
+            next
+          end
+
+          child_env = shard_child_env(cfg: cfg, workers: workers, shard: shard)
+
+          Polyrun::Log.warn "polyrun run-shards: shard #{shard} → #{paths.size} file(s)" if @verbose
+          pid = Process.spawn(child_env, *cmd, *paths)
+          pids << {pid: pid, shard: shard}
+          Polyrun::Debug.log("[parent pid=#{$$}] run-shards: Process.spawn shard=#{shard} child_pid=#{pid} spec_files=#{paths.size}")
+          Polyrun::Log.warn "polyrun run-shards: started shard #{shard} pid=#{pid} (#{paths.size} file(s))" if parallel
+        end
+        pids
+      end
+
+      def run_shards_warn_interleaved(parallel, pid_count)
+        return unless parallel && pid_count > 1
+
+        Polyrun::Log.warn "polyrun run-shards: #{pid_count} children running; RSpec output below may be interleaved."
+        Polyrun::Log.warn "polyrun run-shards: each worker prints its own summary line; the last \"N examples\" line is not a total across shards."
+      end
+
+      def run_shards_wait_all_children(pids)
+        shard_results = []
+        Polyrun::Debug.time("Process.wait (#{pids.size} worker process(es))") do
+          pids.each do |h|
+            Process.wait(h[:pid])
+            exitstatus = $?.exitstatus
+            ok = $?.success?
+            Polyrun::Debug.log("[parent pid=#{$$}] run-shards: Process.wait child_pid=#{h[:pid]} shard=#{h[:shard]} exit=#{exitstatus} success=#{ok}")
+            shard_results << {shard: h[:shard], exitstatus: exitstatus, success: ok}
+          end
+        rescue Interrupt
+          # Do not trap SIGINT: Process.wait raises Interrupt; a trap races and prints Interrupt + SystemExit traces.
+          run_shards_shutdown_on_signal!(pids, 130)
+        rescue SignalException => e
+          raise unless e.signm == "SIGTERM"
+
+          run_shards_shutdown_on_signal!(pids, 143)
+        end
+        shard_results
+      end
+
+      # Best-effort worker teardown then exit. Does not return.
+      def run_shards_shutdown_on_signal!(pids, code)
+        run_shards_terminate_children!(pids)
+        exit(code)
+      rescue Interrupt
+        pids.each do |h|
+          Process.kill(:KILL, h[:pid])
+        rescue Errno::ESRCH
+          # already reaped
+        end
+        pids.each do |h|
+          Process.wait(h[:pid])
+        rescue Errno::ESRCH, Errno::ECHILD, Interrupt
+          # already reaped or give up
+        end
+        exit(code)
+      end
+
+      # Send SIGTERM to each worker PID and wait so Ctrl+C / SIGTERM does not leave orphans.
+      def run_shards_terminate_children!(pids)
+        pids.each do |h|
+          Process.kill(:TERM, h[:pid])
+        rescue Errno::ESRCH
+          # already reaped
+        end
+        pids.each do |h|
+          Process.wait(h[:pid])
+        rescue Errno::ESRCH, Errno::ECHILD
+          # already reaped
+        end
+      end
+
+      def run_shards_merge_or_hint_coverage(ctx)
+        if ctx[:merge_coverage]
+          mo = ctx[:merge_output] || "coverage/merged.json"
+          mf = ctx[:merge_format] || ENV["POLYRUN_MERGE_FORMATS"] || Polyrun::Coverage::Reporting::DEFAULT_MERGE_FORMAT_LIST
+          Polyrun::Debug.log("run-shards: starting post-worker merge_coverage_after_shards → #{mo}")
+          return merge_coverage_after_shards(output: mo, format_list: mf, config_path: ctx[:config_path])
+        end
+
+        if ctx[:parallel]
+          Polyrun::Log.warn <<~MSG
+            polyrun run-shards: coverage — each worker writes coverage/polyrun-fragment-<shard>.json when Polyrun coverage is enabled (POLYRUN_SHARD_INDEX per process).
+            polyrun run-shards: next step — merge with: polyrun merge-coverage -i 'coverage/polyrun-fragment-*.json' -o coverage/merged.json --format json,cobertura,console
+          MSG
+        end
+        0
+      end
+
+      def run_shards_log_failed_reruns(failed, shard_results, plan, parallel, workers, cmd)
+        exit_by_shard = shard_results.each_with_object({}) { |r, h| h[r[:shard]] = r[:exitstatus] }
+        failed_detail = failed.sort.map { |s| "#{s} (exit #{exit_by_shard[s]})" }.join(", ")
+        Polyrun::Log.warn "polyrun run-shards: failed shard(s): #{failed_detail}"
+        if parallel
+          Polyrun::Log.warn "polyrun run-shards: search this log for the failed shard's output, or re-run one shard at a time (below) for a clean RSpec report."
+        end
+        failed.sort.each do |s|
+          paths = plan.shard(s)
+          next if paths.empty?
+
+          rerun = "export POLYRUN_SHARD_INDEX=#{s} POLYRUN_SHARD_TOTAL=#{workers}; "
+          rerun << Shellwords.join(cmd + paths)
+          Polyrun::Log.warn "polyrun run-shards: shard #{s} re-run (same spec list, no interleave): #{rerun}"
+        end
+      end
+    end
+  end
+end

data/lib/polyrun/cli/start_bootstrap.rb

@@ -0,0 +1,99 @@
+module Polyrun
+  class CLI
+    # +polyrun start+ only: run +prepare+ and/or Postgres template+shard DBs before parallel RSpec.
+    module StartBootstrap
+      private
+
+      # Keep in sync with {RunShardsCommand} worker defaults.
+      START_ARG_WORKERS_DEFAULT = 5
+      START_ARG_WORKERS_MAX = 10
+
+      def start_bootstrap!(cfg, argv, config_path)
+        if start_run_prepare?(cfg) && !truthy_env?("POLYRUN_START_SKIP_PREPARE")
+          recipe = cfg.prepare["recipe"] || cfg.prepare[:recipe] || "default"
+          Polyrun::Log.warn "polyrun start: running prepare (recipe=#{recipe})" if @verbose
+          code = cmd_prepare([], config_path)
+          return code if code != 0
+        end
+
+        if start_run_database_provision?(cfg) && !truthy_env?("POLYRUN_START_SKIP_DATABASES")
+          workers = parse_workers_from_start_argv(argv)
+          Polyrun::Log.warn "polyrun start: provisioning test DBs (template + shards 0..#{workers - 1})" if @verbose
+          begin
+            Polyrun::Database::CloneShards.provision!(
+              cfg.databases,
+              workers: workers,
+              rails_root: Dir.pwd,
+              migrate: true,
+              replace: true,
+              force_drop: truthy_env?("POLYRUN_PG_DROP_FORCE"),
+              dry_run: false,
+              silent: !@verbose
+            )
+          rescue Polyrun::Error => e
+            Polyrun::Log.warn "polyrun start: #{e.message}"
+            return 1
+          end
+        end
+        0
+      end
+
+      def start_run_prepare?(cfg)
+        st = cfg.start_config
+        prep = cfg.prepare
+        return false unless prep.is_a?(Hash) && !prep.empty?
+
+        return false if st["prepare"] == false || st[:prepare] == false
+        return true if st["prepare"] == true || st[:prepare] == true
+
+        prepare_recipe_has_side_effects?(prep)
+      end
+
+      def prepare_recipe_has_side_effects?(prep)
+        recipe = (prep["recipe"] || prep[:recipe] || "default").to_s
+        return true if %w[shell assets].include?(recipe)
+        return true if prep["command"] || prep[:command] || prep["commands"] || prep[:commands]
+
+        false
+      end
+
+      def start_run_database_provision?(cfg)
+        st = cfg.start_config
+        dh = cfg.databases
+        return false unless dh.is_a?(Hash)
+
+        template = (dh["template_db"] || dh[:template_db]).to_s
+        return false if template.empty?
+
+        if st["databases"] == true || st[:databases] == true
+          return true
+        end
+        return false if st["databases"] == false || st[:databases] == false
+
+        true
+      end
+
+      def parse_workers_from_start_argv(argv)
+        sep = argv.index("--")
+        head = sep ? argv[0...sep] : argv
+        workers = env_int("POLYRUN_WORKERS", START_ARG_WORKERS_DEFAULT)
+        i = 0
+        while i < head.size
+          if head[i] == "--workers" && head[i + 1]
+            w = Integer(head[i + 1], exception: false)
+            workers = w if w && w >= 1
+            i += 2
+          else
+            i += 1
+          end
+        end
+        workers.clamp(1, START_ARG_WORKERS_MAX)
+      end
+
+      def truthy_env?(name)
+        v = ENV[name].to_s.downcase
+        %w[1 true yes].include?(v)
+      end
+    end
+  end
+end

data/lib/polyrun/cli/timing_command.rb

@@ -0,0 +1,31 @@
+require "optparse"
+
+module Polyrun
+  class CLI
+    module TimingCommand
+      private
+
+      def cmd_merge_timing(argv)
+        inputs = []
+        output = "polyrun_timing.json"
+        parser = OptionParser.new do |opts|
+          opts.banner = "usage: polyrun merge-timing [-i FILE]... [-o OUT] [FILE...]"
+          opts.on("-i", "--input FILE", "Timing JSON fragment (repeatable)") { |f| inputs << f }
+          opts.on("-o", "--output PATH", String) { |v| output = v }
+        end
+        parser.parse!(argv)
+        inputs.concat(argv) if inputs.empty?
+
+        if inputs.empty?
+          Polyrun::Log.warn "merge-timing: need -i FILE or positional paths"
+          return 2
+        end
+
+        out_abs = File.expand_path(output)
+        Polyrun::Timing::Merge.merge_and_write(inputs.map { |p| File.expand_path(p) }, out_abs)
+        Polyrun::Log.puts out_abs
+        0
+      end
+    end
+  end
+end

data/lib/polyrun/cli.rb

@@ -0,0 +1,184 @@
+require "optparse"
+
+require_relative "cli/helpers"
+require_relative "cli/plan_command"
+require_relative "cli/prepare_command"
+require_relative "cli/coverage_commands"
+require_relative "cli/report_commands"
+require_relative "cli/env_commands"
+require_relative "cli/database_commands"
+require_relative "cli/run_shards_command"
+require_relative "cli/queue_command"
+require_relative "cli/timing_command"
+require_relative "cli/init_command"
+require_relative "cli/quick_command"
+
+module Polyrun
+  class CLI
+    include Helpers
+    include PlanCommand
+    include PrepareCommand
+    include CoverageCommands
+    include ReportCommands
+    include EnvCommands
+    include DatabaseCommands
+    include RunShardsCommand
+    include QueueCommand
+    include TimingCommand
+    include InitCommand
+    include QuickCommand
+
+    def self.run(argv = ARGV)
+      new.run(argv)
+    end
+
+    def run(argv)
+      argv = argv.dup
+      config_path = parse_global_cli!(argv)
+      return config_path if config_path.is_a?(Integer)
+
+      command = argv.shift
+      if command.nil?
+        print_help
+        return 0
+      end
+
+      Polyrun::Debug.log_kv(
+        command: command,
+        cwd: Dir.pwd,
+        polyrun_config: config_path,
+        argv_rest: argv.dup,
+        verbose: @verbose
+      )
+
+      dispatch_cli_command(command, argv, config_path)
+    end
+
+    private
+
+    def parse_global_cli!(argv)
+      config_path = ENV["POLYRUN_CONFIG"]
+      @verbose = false
+      while (a = argv.first) && a.start_with?("-") && a != "--"
+        case a
+        when "-c", "--config"
+          argv.shift
+          config_path = argv.shift or break
+        when "-v", "--verbose"
+          @verbose = true
+          argv.shift
+        when "-h", "--help"
+          print_help
+          return 0
+        else
+          break
+        end
+      end
+      config_path
+    end
+
+    def dispatch_cli_command(command, argv, config_path)
+      case command
+      when "help"
+        print_help
+        0
+      when "version"
+        cmd_version
+      else
+        dispatch_cli_command_subcommands(command, argv, config_path)
+      end
+    end
+
+    def dispatch_cli_command_subcommands(command, argv, config_path)
+      case command
+      when "plan"
+        cmd_plan(argv, config_path)
+      when "prepare"
+        cmd_prepare(argv, config_path)
+      when "merge-coverage"
+        cmd_merge_coverage(argv, config_path)
+      when "report-coverage"
+        cmd_report_coverage(argv)
+      when "report-junit"
+        cmd_report_junit(argv)
+      when "report-timing"
+        cmd_report_timing(argv)
+      when "env"
+        cmd_env(argv, config_path)
+      when "merge-timing"
+        cmd_merge_timing(argv)
+      when "db:setup-template"
+        cmd_db_setup_template(argv, config_path)
+      when "db:setup-shard"
+        cmd_db_setup_shard(argv, config_path)
+      when "db:clone-shards"
+        cmd_db_clone_shards(argv, config_path)
+      when "run-shards"
+        cmd_run_shards(argv, config_path)
+      when "parallel-rspec"
+        cmd_parallel_rspec(argv, config_path)
+      when "start"
+        cmd_start(argv, config_path)
+      when "build-paths"
+        cmd_build_paths(config_path)
+      when "init"
+        cmd_init(argv, config_path)
+      when "queue"
+        cmd_queue(argv)
+      when "quick"
+        cmd_quick(argv)
+      else
+        Polyrun::Log.warn "unknown command: #{command}"
+        2
+      end
+    end
+
+    def print_help
+      Polyrun::Log.puts <<~HELP
+        usage: polyrun [global options] <command> [options]
+
+        global:
+          -c, --config PATH    polyrun.yml path (or POLYRUN_CONFIG)
+          -v, --verbose
+          -h, --help
+
+        Trace timing (stderr): DEBUG=1 or POLYRUN_DEBUG=1
+        Branch coverage in JSON fragments: POLYRUN_COVERAGE_BRANCHES=1 (stdlib Coverage; merge-coverage merges branches)
+        polyrun quick coverage: POLYRUN_COVERAGE=1 or (config/polyrun_coverage.yml + POLYRUN_QUICK_COVERAGE=1); POLYRUN_COVERAGE_DISABLE=1 skips
+        Merge wall time (stderr): POLYRUN_PROFILE_MERGE=1 (or verbose / DEBUG)
+        Post-merge formats (run-shards): POLYRUN_MERGE_FORMATS (default: json,lcov,cobertura,console,html)
+        Skip optional script/build_spec_paths.rb before start: POLYRUN_SKIP_BUILD_SPEC_PATHS=1
+        Skip start auto-prepare / auto DB provision: POLYRUN_START_SKIP_PREPARE=1, POLYRUN_START_SKIP_DATABASES=1
+        Skip writing paths_file from partition.paths_build: POLYRUN_SKIP_PATHS_BUILD=1
+        Warn if merge-coverage wall time exceeds N seconds (default 10): POLYRUN_MERGE_SLOW_WARN_SECONDS (0 disables)
+        Parallel RSpec workers: POLYRUN_WORKERS default 5, max 10 (run-shards / parallel-rspec / start)
+
+        commands:
+          version              print version
+          plan                 emit partition manifest JSON
+          prepare              run prepare recipe: default | assets (optional prepare.command overrides bin/rails assets:precompile) | shell (prepare.command required)
+          merge-coverage       merge SimpleCov JSON fragments (json/lcov/cobertura/console)
+          run-shards           fan out N parallel OS processes (POLYRUN_SHARD_*; not Ruby threads); optional --merge-coverage
+          parallel-rspec       run-shards + merge-coverage (defaults to: bundle exec rspec after --)
+          start                parallel-rspec; auto-runs prepare (shell/assets) and db:setup-* when polyrun.yml configures them; legacy script/build_spec_paths.rb if paths_build absent
+          build-paths          write partition.paths_file from partition.paths_build (same as auto step before plan/run-shards)
+          init                 write a starter polyrun.yml or POLYRUN.md from built-in templates (see docs/SETUP_PROFILE.md)
+          queue                file-backed batch queue (init / claim / ack / status)
+          quick                run Polyrun::Quick (describe/it, before/after, let, expect…to, assert_*; optional capybara!)
+          report-coverage      write all coverage formats from one JSON file
+          report-junit         RSpec JSON or Polyrun testcase JSON → JUnit XML (CI)
+          report-timing        print slow-file summary from merged timing JSON
+          merge-timing         merge polyrun_timing_*.json shards
+          env                  print shard + database env (see polyrun.yml databases)
+          db:setup-template    migrate template DB (PostgreSQL)
+          db:setup-shard       CREATE DATABASE shard FROM template (one POLYRUN_SHARD_INDEX)
+          db:clone-shards      migrate templates + DROP/CREATE all shard DBs (replaces clone_shard shell scripts)
+      HELP
+    end
+
+    def cmd_version
+      Polyrun::Log.puts "polyrun #{Polyrun::VERSION}"
+      0
+    end
+  end
+end

data/lib/polyrun/config.rb

@@ -0,0 +1,61 @@
+require "yaml"
+
+module Polyrun
+  # Loads polyrun.yml (or path from POLYRUN_CONFIG / --config).
+  class Config
+    DEFAULT_FILENAMES = %w[polyrun.yml config/polyrun.yml].freeze
+
+    attr_reader :path, :raw
+
+    def self.load(path: nil)
+      path = resolve_path(path)
+      raw =
+        if path && File.file?(path)
+          YAML.safe_load_file(path, permitted_classes: [Symbol], aliases: true) || {}
+        else
+          {}
+        end
+      new(path: path, raw: raw)
+    end
+
+    def self.resolve_path(explicit)
+      return File.expand_path(explicit) if explicit && !explicit.empty?
+
+      DEFAULT_FILENAMES.each do |name|
+        full = File.expand_path(name, Dir.pwd)
+        return full if File.file?(full)
+      end
+      nil
+    end
+
+    def initialize(path:, raw:)
+      @path = path
+      @raw = raw.freeze
+    end
+
+    def partition
+      raw["partition"] || raw[:partition] || {}
+    end
+
+    def prepare
+      raw["prepare"] || raw[:prepare] || {}
+    end
+
+    def coverage
+      raw["coverage"] || raw[:coverage] || {}
+    end
+
+    def databases
+      raw["databases"] || raw[:databases] || {}
+    end
+
+    # Optional +start:+ block: +prepare+ / +databases+ booleans override auto-detection for +polyrun start+.
+    def start_config
+      raw["start"] || raw[:start] || {}
+    end
+
+    def version
+      raw["version"] || raw[:version]
+    end
+  end
+end