polyrun 2.2.7 → 2.2.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ae7b48f9387b3b00e9bb18163b450f29ac09b93c313548b182a837595a1bed02
-  data.tar.gz: 41497f023278ecd79942d184263640653accb8bb34740310c0f21d2981fe3746
+  metadata.gz: 8f6a7a0e969581e53f92c3e1bd4dfbb046c8321fb25601d58be12d4cc8cb6a96
+  data.tar.gz: 0c4625804e0ee0ce3f695570001658f9d907d9102c059258efa9c00fdf16d669
 SHA512:
-  metadata.gz: '09ca1c1d70818a1d7c41f5084109ff96d2b2560f90840ece694b3af3db558f65d0844d0a2e62c0fc15a4b1bce01cb065abb68793620bd08e2d38b4f96948be39'
-  data.tar.gz: f4b992eba7b8fe215ac9e7a66dd3002482f73e2c56cd1566e4021336f280351dd2f6ad5a003a323445f56bd7d445af06d0e07da8bed303542001cc55657afadb
+  metadata.gz: 663f89b311212915efcb030db4cf88feb7f3f78b981746d63ee8c5548fec1abd23e13df3b307f4173601e4b3b829dab9ac56664caecfd929ed48c585deec58c2
+  data.tar.gz: be540c7af7282a2868408a6e8fa7837976ae2ffe443acbec7e65bb6e881d0bce419a344cf75573cadb2af0f562272032eabaf30564e2fab9a998f76029e37c07

data/CHANGELOG.md

@@ -1,6 +1,16 @@
 # CHANGELOG
 
-## Unreleased
+## 2.2.8 (2026-11-04)
+
+- Honor top-level `workers:` in `polyrun.yml` when `POLYRUN_WORKERS` is unset (`polyrun config workers`, `start`, `run-shards`, `run-queue`, `doctor`).
+- Resolve coverage from `config/polyrun_coverage.yml` when that file is present, and otherwise from inline `coverage:` in `polyrun.yml`. Map `formats` and a directory `output_path` to the report keys.
+- Apply the selected suite and an explicit `-c` or `POLYRUN_CONFIG` to coverage collection, the merge gate, and `polyrun doctor`.
+- Add `polyrun validate` for unknown top-level keys and a non-mapping YAML root.
+- Add `version`, `start`, empty `hooks`, and `merge_failures` commentary to the Rails `polyrun init` template.
+- Add named `suites:` overlays selected with `--suite` or `POLYRUN_SUITE` (partition membership, workers, and related top-level keys).
+- Add `polyrun doctor` for the effective config summary (file, suite, start gates, database adapter and shards, coverage source).
+- Accept `POLYRUN_SKIP_PREPARE` and `POLYRUN_SKIP_DATABASES` as the skip switches. Keep `POLYRUN_START_SKIP_*` working, with a deprecation warning.
+- Add `polyrun init --profile rails-prepare-task`, which writes `lib/tasks/polyrun_prepare.rake`.
 
 ## 2.2.7 (2026-11-04)
 

data/lib/polyrun/cli/coverage_commands.rb

@@ -100,7 +100,7 @@ module Polyrun
         code = merge_coverage_after_shards_run_merge(files, output, format_list, config_path)
         return code unless code == 0
 
-        merge_coverage_after_shards_strict_gate(output, code)
+        merge_coverage_after_shards_strict_gate(output, code, config_path: config_path)
       rescue JSON::ParserError => e
         Polyrun::Log.warn "polyrun run-shards: merged coverage JSON parse failed: #{e.message}"
         1
@@ -126,8 +126,8 @@ module Polyrun
         end
       end
 
-      def merge_coverage_after_shards_strict_gate(output, code)
-        gate = coverage_minimum_line_gate_from_polyrun_coverage_yml
+      def merge_coverage_after_shards_strict_gate(output, code, config_path: nil)
+        gate = coverage_minimum_line_gate_from_polyrun_coverage_yml(config_path: config_path)
         Polyrun::Debug.log_kv(
           coverage_gate_config: "polyrun_coverage.yml",
           gate: gate.inspect

data/lib/polyrun/cli/doctor_command.rb

@@ -0,0 +1,94 @@
+require_relative "../coverage/config_resolve"
+require_relative "skip_env"
+
+module Polyrun
+  class CLI
+    module DoctorCommand
+      private
+
+      def cmd_doctor(argv, config_path)
+        unless argv.empty?
+          Polyrun::Log.warn "polyrun doctor: unexpected arguments: #{argv.join(" ")}"
+          return 2
+        end
+
+        cfg = Polyrun::Config.load(path: config_path || ENV["POLYRUN_CONFIG"])
+        lines = doctor_lines(cfg)
+        lines.each { |line| Polyrun::Log.puts line }
+        0
+      end
+
+      def doctor_lines(cfg)
+        workers = Polyrun::Config::Resolver.parallel_worker_count(cfg).clamp(1, Polyrun::Config::MAX_PARALLEL_WORKERS)
+        cov = Polyrun::Coverage::ConfigResolve.load(root: Dir.pwd, polyrun_config_path: cfg.path)
+        lines = []
+        lines << "polyrun doctor"
+        lines << "  config: #{cfg.path || "(none)"}"
+        lines << "  suite: #{cfg.suite || "(none)"}"
+        lines << "  workers: #{workers}"
+        lines.concat(doctor_start_lines(cfg))
+        lines.concat(doctor_database_lines(cfg, workers))
+        lines.concat(doctor_coverage_lines(cov))
+        lines.concat(doctor_warning_lines(cfg, workers))
+        lines
+      end
+
+      def doctor_start_lines(cfg)
+        prep = start_run_prepare?(cfg)
+        dbs = start_databases_provision_wanted?(cfg)
+        [
+          "  start.prepare: #{doctor_yes_no(prep, SkipEnv.skip_prepare?)}",
+          "  start.databases: #{doctor_yes_no(dbs, SkipEnv.skip_databases?)}"
+        ]
+      end
+
+      def doctor_yes_no(wanted, skipped)
+        text = wanted ? "yes" : "no"
+        skipped ? "#{text} (skipped by env)" : text
+      end
+
+      def doctor_database_lines(cfg, workers)
+        dh = cfg.databases
+        return ["  databases: (none)"] unless dh.is_a?(Hash) && !dh.empty?
+
+        adapter = Polyrun::Database::UrlBuilder::ConnectionInfer.infer_adapter_name(dh)
+        lines = ["  databases.adapter: #{adapter || "(unknown)"}"]
+        if adapter == "postgresql"
+          names = (0...workers).map do |i|
+            Polyrun::Database::UrlBuilder.shard_database_name(dh, shard_index: i)
+          rescue Polyrun::Error
+            nil
+          end.compact
+          lines << "  databases.shards: #{names.join(", ")}" unless names.empty?
+          lines << "  databases.provision: CloneShards (PostgreSQL)"
+        else
+          lines << "  databases.provision: URL shaping only (no auto clone)"
+        end
+        lines
+      rescue Polyrun::Error => e
+        ["  databases: error (#{e.message})"]
+      end
+
+      def doctor_coverage_lines(cov)
+        disable = %w[1 true yes].include?(ENV["POLYRUN_COVERAGE_DISABLE"].to_s.downcase)
+        [
+          "  coverage.source: #{cov["coverage_config_source"] || "none"}",
+          "  coverage.disable: #{disable ? "yes (POLYRUN_COVERAGE_DISABLE)" : "no"}"
+        ]
+      end
+
+      def doctor_warning_lines(cfg, workers)
+        warnings = []
+        matrix_total = ENV["POLYRUN_SHARD_TOTAL"].to_s
+        if !matrix_total.empty? && matrix_total.to_i > 1 && workers > 1
+          warnings << "  warn: matrix POLYRUN_SHARD_TOTAL=#{matrix_total} and in-process workers=#{workers} are both set; confirm fragment naming and merge story"
+        end
+        suite_files = Dir.glob("polyrun.*.yml").reject { |p| p == "polyrun.yml" }
+        if cfg.path && !suite_files.empty? && cfg.suite.nil?
+          warnings << "  warn: named suite files present (#{suite_files.sort.join(", ")}); prefer suites: in root polyrun.yml + --suite"
+        end
+        warnings
+      end
+    end
+  end
+end

data/lib/polyrun/cli/help.rb

@@ -9,6 +9,7 @@ module Polyrun
 
           global:
             -c, --config PATH    polyrun.yml path (or POLYRUN_CONFIG)
+            --suite NAME         apply suites.NAME overlay from polyrun.yml (or POLYRUN_SUITE)
             -v, --verbose
             -h, --help
 
@@ -18,11 +19,13 @@ module Polyrun
           Hooks shell output: POLYRUN_HOOKS_VERBOSE=1 or -v / POLYRUN_VERBOSE=1 (or DEBUG); failures always print
           Merge profiling (stderr): POLYRUN_PROFILE_MERGE=1 (or verbose / DEBUG)
           Post-merge formats (run-shards): POLYRUN_MERGE_FORMATS (default: json,lcov,cobertura,console,html,csv,markdown)
-          Start skips: POLYRUN_SKIP_BUILD_SPEC_PATHS=1, POLYRUN_START_SKIP_PREPARE=1, POLYRUN_START_SKIP_DATABASES=1
+          Start skips: POLYRUN_SKIP_PREPARE=1, POLYRUN_SKIP_DATABASES=1 (legacy aliases: POLYRUN_START_SKIP_PREPARE, POLYRUN_START_SKIP_DATABASES); POLYRUN_SKIP_BUILD_SPEC_PATHS=1
           Paths build skip: POLYRUN_SKIP_PATHS_BUILD=1
+          Named suite: --suite NAME or POLYRUN_SUITE (see suites: in polyrun.yml)
           Slow merge warning (seconds, default 10; 0 disables): POLYRUN_MERGE_SLOW_WARN_SECONDS
           Failure merge: run-shards --merge-failures (enable failure fragments in test setup); POLYRUN_MERGE_FAILURES=1, POLYRUN_FAILURE_FRAGMENT_DIR, POLYRUN_MERGED_FAILURES_OUT
-          Parallel workers: POLYRUN_WORKERS default 5, max 10 (run-shards / parallel-rspec / start). CI local processes per job: POLYRUN_SHARD_PROCESSES or ci-shard --shard-processes (not POLYRUN_WORKERS)
+          Parallel workers: POLYRUN_WORKERS, else top-level workers: in polyrun.yml, else default 5, max 10 (run-shards / parallel-rspec / start). CI local processes per job: POLYRUN_SHARD_PROCESSES or ci-shard --shard-processes (not POLYRUN_WORKERS)
+          Coverage config: config/polyrun_coverage.yml overlays inline coverage: in polyrun.yml (formats -> report_formats; directory output_path -> report_output_dir)
           Per-worker wall timeout: --worker-timeout SEC or POLYRUN_WORKER_TIMEOUT_SEC. Exit 124; parent stops remaining workers.
           Per-worker idle timeout: --worker-idle-timeout SEC or POLYRUN_WORKER_IDLE_TIMEOUT_SEC after a progress ping (POLYRUN_WORKER_PING_FILE). Enable pings in test setup. Exit 125. Optional periodic pings: POLYRUN_WORKER_PING_THREAD=1 (POLYRUN_WORKER_PING_INTERVAL_SEC).
           Worker output routing (opt-in): POLYRUN_WORKER_OUTPUT_ROUTING=1 or POLYRUN_WORKER_LOG_DIR; per-shard logs under tmp/polyrun/workers (POLYRUN_WORKER_OUTPUT_PREFIX=0 for log-only)
@@ -61,6 +64,8 @@ module Polyrun
             merge-spec-quality   merge polyrun-spec-quality-fragment-*.jsonl shards
             report-spec-quality  spec quality report from merged JSON (text/json/csv/markdown)
             config               print effective config by dotted path (loaded YAML plus merged prepare.env, resolved partition shard fields, workers)
+            validate             check polyrun.yml top-level keys (unknown keys exit 1)
+            doctor               print effective config summary (file, suite, start gates, DBs, coverage)
             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)

data/lib/polyrun/cli/helpers.rb

@@ -89,24 +89,10 @@ module Polyrun
         [abs]
       end
 
-      # Same rounding/strict semantics as {Polyrun::Coverage::Collector} for +config/polyrun_coverage.yml+.
-      def coverage_minimum_line_gate_from_polyrun_coverage_yml
-        path = File.join(Dir.pwd, "config", "polyrun_coverage.yml")
-        return nil unless File.file?(path)
-
-        data = YAML.safe_load_file(path, permitted_classes: [Symbol], aliases: true)
-        return nil unless data.is_a?(Hash)
-
-        min = data["minimum_line_percent"] || data[:minimum_line_percent]
-        return nil if min.nil?
-
-        sv = data["strict"] if data.key?("strict")
-        sv = data[:strict] if !data.key?("strict") && data.key?(:strict)
-        strict = sv.nil? || sv
-
-        {minimum: min.to_f, strict: strict != false}
-      rescue Psych::SyntaxError, ArgumentError, TypeError
-        nil
+      # Same rounding/strict semantics as {Polyrun::Coverage::Collector}; see {Coverage::ConfigResolve}.
+      def coverage_minimum_line_gate_from_polyrun_coverage_yml(config_path: nil)
+        require_relative "../coverage/config_resolve"
+        Polyrun::Coverage::ConfigResolve.minimum_line_gate(root: Dir.pwd, polyrun_config_path: config_path)
       end
 
       def load_partition_constraints(pc, constraints_path)

data/lib/polyrun/cli/init_command.rb

@@ -7,6 +7,7 @@ module Polyrun
       INIT_PROFILES = {
         "gem" => "minimal_gem.polyrun.yml",
         "rails" => "rails_prepare.polyrun.yml",
+        "rails-prepare-task" => "rails_prepare_task.rake",
         "ci-matrix" => "ci_matrix.polyrun.yml",
         "spec-quality" => "polyrun_spec_quality.yml",
         "doc" => "POLYRUN.md"
@@ -98,6 +99,7 @@ module Polyrun
         case profile
         when "doc" then "POLYRUN.md"
         when "spec-quality" then "config/polyrun_spec_quality.yml"
+        when "rails-prepare-task" then "lib/tasks/polyrun_prepare.rake"
         else "polyrun.yml"
         end
       end

data/lib/polyrun/cli/run_queue_command.rb

@@ -42,7 +42,7 @@ module Polyrun
           plan_command_register_partition_options!(opts, ctx)
         end.parse!(head)
 
-        workers ||= env_int("POLYRUN_WORKERS", Polyrun::Config::DEFAULT_PARALLEL_WORKERS)
+        workers ||= Polyrun::Config::Resolver.parallel_worker_count(cfg)
         unless workers.is_a?(Integer) && workers.between?(1, Polyrun::Config::MAX_PARALLEL_WORKERS)
           Polyrun::Log.warn "polyrun run-queue: --workers must be between 1 and #{Polyrun::Config::MAX_PARALLEL_WORKERS}"
           return 2

data/lib/polyrun/cli/run_shards_plan_boot_phases.rb

@@ -8,8 +8,8 @@ module Polyrun
       private
 
       # @return [:fail, Integer] | [:ok, Hash, Array<String>]
-      def run_shards_plan_phase_a(head, cmd, pc)
-        o = run_shards_plan_options(head, pc)
+      def run_shards_plan_phase_a(head, cmd, pc, cfg = nil)
+        o = run_shards_plan_options(head, pc, cfg: cfg)
         code = Polyrun::Partition::PathsBuild.apply!(partition: pc, cwd: Dir.pwd)
         return [:fail, code] if code != 0
 

data/lib/polyrun/cli/run_shards_plan_options.rb

@@ -5,17 +5,17 @@ module Polyrun
     module RunShardsPlanOptions
       private
 
-      def run_shards_plan_options(head, pc)
-        st = run_shards_plan_options_state(pc)
+      def run_shards_plan_options(head, pc, cfg: nil)
+        st = run_shards_plan_options_state(pc, cfg: cfg)
         run_shards_plan_options_parse!(head, st)
         st[:paths_file] ||= pc["paths_file"] || pc[:paths_file]
         st[:timing_granularity] = resolve_partition_timing_granularity(pc, st[:timing_granularity])
         st
       end
 
-      def run_shards_plan_options_state(pc)
+      def run_shards_plan_options_state(pc, cfg: nil)
         {
-          workers: env_int("POLYRUN_WORKERS", Polyrun::Config::DEFAULT_PARALLEL_WORKERS),
+          workers: Polyrun::Config::Resolver.parallel_worker_count(cfg),
           paths_file: nil,
           strategy: (pc["strategy"] || pc[:strategy] || "round_robin").to_s,
           strategy_explicit: !!(pc["strategy"] || pc[:strategy]),

data/lib/polyrun/cli/run_shards_planning.rb

@@ -16,7 +16,7 @@ module Polyrun
         return boot if boot.size == 2
 
         run_t0, head, cmd, cfg, pc = boot
-        phase = run_shards_plan_phase_a(head, cmd, pc)
+        phase = run_shards_plan_phase_a(head, cmd, pc, cfg)
         return [phase[1], nil] if phase[0] == :fail
 
         _tag, o, cmd = phase

data/lib/polyrun/cli/skip_env.rb

@@ -0,0 +1,34 @@
+module Polyrun
+  class CLI
+    # Canonical start skip flags are +POLYRUN_SKIP_PREPARE+ / +POLYRUN_SKIP_DATABASES+.
+    # Legacy +POLYRUN_START_SKIP_*+ aliases remain accepted during the deprecation window.
+    module SkipEnv
+      module_function
+
+      def skip_prepare?(env = ENV)
+        truthy?(env, "POLYRUN_SKIP_PREPARE") ||
+          legacy_truthy?(env, "POLYRUN_START_SKIP_PREPARE", "POLYRUN_SKIP_PREPARE")
+      end
+
+      def skip_databases?(env = ENV)
+        truthy?(env, "POLYRUN_SKIP_DATABASES") ||
+          legacy_truthy?(env, "POLYRUN_START_SKIP_DATABASES", "POLYRUN_SKIP_DATABASES")
+      end
+
+      def truthy?(env, name)
+        %w[1 true yes].include?(env[name].to_s.downcase)
+      end
+      private_class_method :truthy?
+
+      def legacy_truthy?(env, legacy, canonical)
+        return false unless truthy?(env, legacy)
+
+        unless truthy?(env, canonical)
+          Polyrun::Log.warn "polyrun: #{legacy}=1 is deprecated; use #{canonical}=1"
+        end
+        true
+      end
+      private_class_method :legacy_truthy?
+    end
+  end
+end

data/lib/polyrun/cli/start_bootstrap.rb

@@ -1,3 +1,5 @@
+require_relative "skip_env"
+
 module Polyrun
   class CLI
     # +polyrun start+ only: run +prepare+ and/or Postgres template+shard DBs before parallel RSpec.
@@ -5,14 +7,14 @@ module Polyrun
       private
 
       def start_bootstrap!(cfg, argv, config_path)
-        if start_run_prepare?(cfg) && !truthy_env?("POLYRUN_START_SKIP_PREPARE")
+        if start_run_prepare?(cfg) && !SkipEnv.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
 
-        return 0 unless start_databases_provision_wanted?(cfg) && !truthy_env?("POLYRUN_START_SKIP_DATABASES")
+        return 0 unless start_databases_provision_wanted?(cfg) && !SkipEnv.skip_databases?
 
         dh = cfg.databases
         adapter = Polyrun::Database::UrlBuilder::ConnectionInfer.infer_adapter_name(dh)
@@ -20,7 +22,7 @@ module Polyrun
           return start_non_postgresql_databases_outcome(cfg, adapter)
         end
 
-        workers = parse_workers_from_start_argv(argv)
+        workers = parse_workers_from_start_argv(argv, cfg)
         Polyrun::Log.warn "polyrun start: provisioning test DBs (template + shards 0..#{workers - 1})" if @verbose
         begin
           Polyrun::Database::CloneShards.provision!(
@@ -94,10 +96,10 @@ module Polyrun
         0
       end
 
-      def parse_workers_from_start_argv(argv)
+      def parse_workers_from_start_argv(argv, cfg = nil)
         sep = argv.index("--")
         head = sep ? argv[0...sep] : argv
-        workers = env_int("POLYRUN_WORKERS", Polyrun::Config::DEFAULT_PARALLEL_WORKERS)
+        workers = Polyrun::Config::Resolver.parallel_worker_count(cfg)
         i = 0
         while i < head.size
           if head[i] == "--workers" && head[i + 1]

data/lib/polyrun/cli/validate_command.rb

@@ -0,0 +1,26 @@
+require_relative "../config/schema"
+
+module Polyrun
+  class CLI
+    module ValidateCommand
+      private
+
+      def cmd_validate(argv, config_path)
+        unless argv.empty?
+          Polyrun::Log.warn "polyrun validate: unexpected arguments: #{argv.join(" ")}"
+          return 2
+        end
+
+        cfg = Polyrun::Config.load(path: config_path || ENV["POLYRUN_CONFIG"])
+        result = Polyrun::Config::Schema.validate(cfg)
+        result[:messages].each { |m| Polyrun::Log.warn m }
+        if result[:ok]
+          Polyrun::Log.puts "polyrun validate: ok (#{cfg.path || "no file"})"
+          0
+        else
+          1
+        end
+      end
+    end
+  end
+end

data/lib/polyrun/cli.rb

@@ -1,4 +1,4 @@
-# rubocop:disable Polyrun/FileLength -- CLI dispatch + require wiring
+# rubocop:disable Polyrun/FileLength, Metrics/ClassLength -- CLI dispatch + require wiring
 require "optparse"
 
 require_relative "cli/helpers"
@@ -20,6 +20,8 @@ require_relative "cli/quick_command"
 require_relative "cli/ci_shard_run_parse"
 require_relative "cli/ci_shard_run_command"
 require_relative "cli/config_command"
+require_relative "cli/validate_command"
+require_relative "cli/doctor_command"
 require_relative "cli/default_run"
 require_relative "cli/hooks_command"
 require_relative "cli/help"
@@ -35,7 +37,7 @@ module Polyrun
     DISPATCH_SUBCOMMAND_NAMES = %w[
       plan prepare merge-coverage merge-failures merge-spec-quality report-coverage report-junit report-timing report-spec-quality report-benchmark bench
       env config merge-timing db:setup-template db:setup-shard db:clone-shards
-      run-shards parallel-rspec parallel-minitest parallel-quick start build-paths init queue run-queue quick hook
+      run-shards parallel-rspec parallel-minitest parallel-quick start build-paths init queue run-queue quick hook validate doctor
     ].freeze
 
     # First argv token that is a normal subcommand (not a path); if argv[0] is not here but looks like paths, run implicit parallel.
@@ -62,6 +64,8 @@ module Polyrun
     include CiShardRunParse
     include CiShardRunCommand
     include ConfigCommand
+    include ValidateCommand
+    include DoctorCommand
     include DefaultRun
     include HooksCommand
     include Help
@@ -71,10 +75,14 @@ module Polyrun
     end
 
     def run(argv)
+      original_suite = ENV["POLYRUN_SUITE"]
+      original_config = ENV["POLYRUN_CONFIG"]
       argv = argv.dup
       config_path = parse_global_cli!(argv)
       return config_path if config_path.is_a?(Integer)
 
+      ENV["POLYRUN_CONFIG"] = File.expand_path(config_path) if config_path
+
       if argv.empty?
         Polyrun::Debug.log_kv(
           command: "(default)",
@@ -111,6 +119,9 @@ module Polyrun
     rescue Polyrun::Error => e
       Polyrun::Log.warn "polyrun: #{e.message}"
       2
+    ensure
+      ENV["POLYRUN_SUITE"] = original_suite
+      ENV["POLYRUN_CONFIG"] = original_config
     end
 
     private
@@ -123,6 +134,18 @@ module Polyrun
         when "-c", "--config"
           argv.shift
           config_path = argv.shift or break
+        when "--suite"
+          argv.shift
+          name = argv.shift
+          raise Polyrun::Error, "--suite requires a name" if name.nil? || name.strip.empty? || name.start_with?("-")
+
+          ENV["POLYRUN_SUITE"] = name
+        when /\A--suite=(.*)\z/
+          name = Regexp.last_match(1)
+          raise Polyrun::Error, "--suite requires a name" if name.strip.empty?
+
+          ENV["POLYRUN_SUITE"] = name
+          argv.shift
         when "-v", "--verbose"
           @verbose = true
           ENV["POLYRUN_VERBOSE"] = "1"
@@ -170,6 +193,10 @@ module Polyrun
         cmd_env(argv, config_path)
       when "config"
         cmd_config(argv, config_path)
+      when "validate"
+        cmd_validate(argv, config_path)
+      when "doctor"
+        cmd_doctor(argv, config_path)
       when "merge-timing"
         cmd_merge_timing(argv)
       when "merge-spec-quality"
@@ -223,4 +250,4 @@ module Polyrun
     end
   end
 end
-# rubocop:enable Polyrun/FileLength
+# rubocop:enable Polyrun/FileLength, Metrics/ClassLength

data/lib/polyrun/config/effective.rb

@@ -49,7 +49,8 @@ module Polyrun
           )
           base["partition"] = part
 
-          base["workers"] = r.parallel_worker_count_default(env)
+          base["workers"] = r.parallel_worker_count(cfg, env)
+          base["suite"] = cfg.suite if cfg.respond_to?(:suite) && cfg.suite
 
           base
         end

data/lib/polyrun/config/resolver.rb

@@ -73,6 +73,33 @@ module Polyrun
       def parallel_worker_count_default(env = ENV)
         env_int("POLYRUN_WORKERS", Polyrun::Config::DEFAULT_PARALLEL_WORKERS, env)
       end
+
+      # +POLYRUN_WORKERS+ then top-level YAML +workers:+ then {Config::DEFAULT_PARALLEL_WORKERS}.
+      def parallel_worker_count(cfg = nil, env = ENV)
+        s = env["POLYRUN_WORKERS"]
+        unless s.nil? || s.empty?
+          i = Integer(s, exception: false)
+          return i unless i.nil?
+        end
+
+        yaml_workers = yaml_top_level_workers(cfg)
+        return yaml_workers unless yaml_workers.nil?
+
+        Polyrun::Config::DEFAULT_PARALLEL_WORKERS
+      end
+
+      def yaml_top_level_workers(cfg)
+        return nil unless cfg
+
+        raw = cfg.respond_to?(:raw) ? cfg.raw : cfg
+        return nil unless raw.is_a?(Hash)
+
+        v = raw["workers"] || raw[:workers]
+        return nil if v.nil? || v.to_s.empty?
+
+        Integer(v, exception: false)
+      end
+      private_class_method :yaml_top_level_workers
     end
   end
 end

data/lib/polyrun/config/schema.rb

@@ -0,0 +1,34 @@
+module Polyrun
+  class Config
+    # Lightweight top-level key checks for +polyrun validate+.
+    module Schema
+      KNOWN_TOP_LEVEL = %w[
+        version
+        partition
+        prepare
+        coverage
+        databases
+        start
+        hooks
+        reporting
+        workers
+        suites
+      ].freeze
+
+      module_function
+
+      def validate(cfg)
+        raw = cfg.raw
+        return {ok: true, messages: ["polyrun validate: no config file found (empty defaults)"]} if cfg.path.nil?
+
+        unless raw.is_a?(Hash)
+          return {ok: false, messages: ["polyrun validate: config root must be a mapping"]}
+        end
+
+        unknown = raw.keys.map(&:to_s) - KNOWN_TOP_LEVEL
+        messages = unknown.sort.map { |k| "polyrun validate: unknown top-level key #{k.inspect}" }
+        {ok: messages.empty?, messages: messages}
+      end
+    end
+  end
+end

data/lib/polyrun/config/suite.rb

@@ -0,0 +1,104 @@
+module Polyrun
+  class Config
+    # Applies a named +suites:+ overlay onto a loaded polyrun.yml hash.
+    module Suite
+      PARTITION_KEYS = %w[
+        paths_file shard_total shard_index strategy seed timing_file timing_granularity
+        constraints constraints_file shard_weights suite paths_build shard_processes
+        shard_workers workers_per_shard
+      ].freeze
+
+      TOP_MERGE_KEYS = %w[workers prepare start hooks reporting coverage databases].freeze
+
+      module_function
+
+      def merge(raw, suite_name)
+        name = suite_name.to_s.strip
+        base = deep_stringify(raw.is_a?(Hash) ? raw : {})
+        return [base, nil] if name.empty?
+
+        suites = base["suites"]
+        unless suites.is_a?(Hash)
+          raise Polyrun::Error, "polyrun: suites: map is required when selecting suite #{name.inspect}"
+        end
+
+        overlay = suites[name]
+        unless overlay.is_a?(Hash)
+          available = suites.keys.map(&:to_s).sort.join(", ")
+          raise Polyrun::Error, "polyrun: unknown suite #{name.inspect} (known: #{available})"
+        end
+
+        apply_overlay!(base, deep_stringify(overlay))
+        [base, name]
+      end
+
+      def apply_overlay!(base, overlay)
+        merge_partition_block!(base, overlay)
+        merge_partition_shortcuts!(base, overlay)
+        merge_top_keys!(base, overlay)
+      end
+      private_class_method :apply_overlay!
+
+      def merge_partition_block!(base, overlay)
+        return unless overlay["partition"].is_a?(Hash)
+
+        base["partition"] = deep_merge_hashes(base["partition"] || {}, overlay["partition"])
+      end
+      private_class_method :merge_partition_block!
+
+      def merge_partition_shortcuts!(base, overlay)
+        PARTITION_KEYS.each do |key|
+          next unless overlay.key?(key)
+
+          base["partition"] ||= {}
+          base["partition"][key] =
+            if key == "paths_build" && base["partition"][key].is_a?(Hash) && overlay[key].is_a?(Hash)
+              deep_merge_hashes(base["partition"][key], overlay[key])
+            else
+              overlay[key]
+            end
+        end
+      end
+      private_class_method :merge_partition_shortcuts!
+
+      def merge_top_keys!(base, overlay)
+        TOP_MERGE_KEYS.each do |key|
+          next unless overlay.key?(key)
+
+          base[key] =
+            if base[key].is_a?(Hash) && overlay[key].is_a?(Hash)
+              deep_merge_hashes(base[key], overlay[key])
+            else
+              overlay[key]
+            end
+        end
+      end
+      private_class_method :merge_top_keys!
+
+      def deep_stringify(obj)
+        case obj
+        when Hash
+          obj.each_with_object({}) { |(k, v), out| out[k.to_s] = deep_stringify(v) }
+        when Array
+          obj.map { |e| deep_stringify(e) }
+        else
+          obj
+        end
+      end
+      private_class_method :deep_stringify
+
+      def deep_merge_hashes(base, overlay)
+        a = base.dup
+        overlay.each do |k, v|
+          a[k] = if a[k].is_a?(Hash) && v.is_a?(Hash)
+            deep_merge_hashes(a[k], v)
+          else
+            v
+          end
+        end
+        a
+      end
+      private_class_method :deep_merge_hashes
+    end
+  end
+end

data/lib/polyrun/config.rb

@@ -9,9 +9,9 @@ module Polyrun
     DEFAULT_PARALLEL_WORKERS = 5
     MAX_PARALLEL_WORKERS = 10
 
-    attr_reader :path, :raw
+    attr_reader :path, :raw, :suite
 
-    def self.load(path: nil)
+    def self.load(path: nil, suite: nil)
       explicit = path && !path.to_s.strip.empty?
       resolved = resolve_path(path)
       if explicit && !(resolved && File.file?(resolved))
@@ -20,11 +20,16 @@ module Polyrun
 
       raw =
         if resolved && File.file?(resolved)
-          YAML.safe_load_file(resolved, permitted_classes: [Symbol], aliases: true) || {}
+          YAML.safe_load_file(resolved, permitted_classes: [Symbol], aliases: true)
         else
           {}
         end
-      new(path: resolved, raw: raw)
+      raw = {} if raw.nil?
+      raise Polyrun::Error, "polyrun config root must be a mapping" unless raw.is_a?(Hash)
+
+      suite_name = (suite.nil? || suite.to_s.strip.empty?) ? ENV["POLYRUN_SUITE"] : suite
+      merged, applied = Suite.merge(raw, suite_name)
+      new(path: resolved, raw: merged, suite: applied)
     end
 
     def self.resolve_path(explicit)
@@ -37,8 +42,9 @@ module Polyrun
       nil
     end
 
-    def initialize(path:, raw:)
+    def initialize(path:, raw:, suite: nil)
       @path = path
+      @suite = suite
       @raw = raw.freeze
     end
 
@@ -76,8 +82,14 @@ module Polyrun
     def reporting
       raw["reporting"] || raw[:reporting] || {}
     end
+
+    def suites
+      raw["suites"] || raw[:suites] || {}
+    end
   end
 end
 
+require_relative "config/suite"
 require_relative "config/resolver"
 require_relative "config/effective"
+require_relative "config/schema"

data/lib/polyrun/coverage/config_resolve.rb

@@ -0,0 +1,131 @@
+require "yaml"
+require_relative "../config/suite"
+
+module Polyrun
+  module Coverage
+    # Resolves coverage settings for {Rails.start!} and CLI gates.
+    #
+    # Order: explicit +config_path+ when that file exists; else +config/polyrun_coverage.yml+
+    # when present; else inline +coverage:+ from +polyrun.yml+ (or +POLYRUN_CONFIG+).
+    # Aliases: +formats+ -> +report_formats+; directory-like +output_path+ -> +report_output_dir+.
+    module ConfigResolve
+      module_function
+
+      DEFAULT_FILE = File.join("config", "polyrun_coverage.yml").freeze
+      POLYRUN_YML_NAMES = %w[polyrun.yml config/polyrun.yml].freeze
+      META_KEYS = %w[coverage_config_source].freeze
+
+      def load(root:, config_path: nil, polyrun_config_path: nil)
+        root = File.expand_path(root)
+        file_path, file_hash = load_file_coverage(root, config_path)
+        if file_path
+          chosen = file_hash
+          source = relative_or_basename(file_path)
+        else
+          inline_path = resolve_polyrun_yml(root, polyrun_config_path)
+          chosen = load_inline_coverage(inline_path)
+          source = chosen.empty? ? "none" : relative_or_basename(inline_path)
+        end
+        normalize_aliases!(chosen, root)
+        chosen["coverage_config_source"] = source
+        chosen
+      end
+
+      def minimum_line_gate(root: Dir.pwd, config_path: nil, polyrun_config_path: nil)
+        data = load(root: root, config_path: config_path, polyrun_config_path: polyrun_config_path)
+        min = data["minimum_line_percent"]
+        return nil if min.nil?
+
+        strict = data.key?("strict") ? data["strict"] != false : true
+        {minimum: min.to_f, strict: strict}
+      end
+
+      def load_inline_coverage(path)
+        return {} unless path
+
+        raw = YAML.safe_load_file(path, permitted_classes: [Symbol], aliases: true)
+        return {} unless raw.is_a?(Hash)
+
+        raw, = Polyrun::Config::Suite.merge(raw, ENV["POLYRUN_SUITE"])
+        cov = raw["coverage"] || raw[:coverage]
+        cov.is_a?(Hash) ? stringify_keys(cov) : {}
+      rescue Psych::SyntaxError, ArgumentError, TypeError
+        {}
+      end
+      private_class_method :load_inline_coverage
+
+      def load_file_coverage(root, config_path)
+        path =
+          if config_path && !config_path.to_s.strip.empty?
+            File.expand_path(config_path.to_s)
+          else
+            File.join(root, DEFAULT_FILE)
+          end
+        return [nil, {}] unless File.file?(path)
+
+        data = YAML.safe_load_file(path, permitted_classes: [Symbol], aliases: true)
+        hash = data.is_a?(Hash) ? stringify_keys(data) : {}
+        [path, hash]
+      rescue Psych::SyntaxError, ArgumentError, TypeError
+        [path, {}]
+      end
+      private_class_method :load_file_coverage
+
+      def resolve_polyrun_yml(root, explicit)
+        if explicit && !explicit.to_s.strip.empty?
+          p = File.expand_path(explicit.to_s)
+          return p if File.file?(p)
+
+          return nil
+        end
+
+        env = ENV["POLYRUN_CONFIG"]
+        if env && !env.empty?
+          p = File.expand_path(env)
+          return p if File.file?(p)
+        end
+
+        POLYRUN_YML_NAMES.each do |name|
+          full = File.expand_path(name, root)
+          return full if File.file?(full)
+        end
+        nil
+      end
+      private_class_method :resolve_polyrun_yml
+
+      def normalize_aliases!(h, root)
+        if !h.key?("report_formats") && h.key?("formats")
+          h["report_formats"] = Array(h.delete("formats"))
+        end
+        return if h.key?("report_output_dir")
+        return unless h.key?("output_path")
+
+        out = h["output_path"].to_s
+        return if out.empty? || out.end_with?(".json")
+
+        h["report_output_dir"] = File.expand_path(out, root)
+        h.delete("output_path")
+      end
+      private_class_method :normalize_aliases!
+
+      def relative_or_basename(path)
+        return DEFAULT_FILE if path.end_with?(DEFAULT_FILE)
+
+        File.basename(path)
+      end
+      private_class_method :relative_or_basename
+
+      def stringify_keys(obj)
+        case obj
+        when Hash
+          obj.each_with_object({}) { |(k, v), out| out[k.to_s] = stringify_keys(v) }
+        when Array
+          obj.map { |e| stringify_keys(e) }
+        else
+          obj
+        end
+      end
+      private_class_method :stringify_keys
+    end
+  end
+end

data/lib/polyrun/coverage/rails.rb

@@ -2,13 +2,15 @@ require "yaml"
 
 require_relative "collector"
 require_relative "formatter"
+require_relative "config_resolve"
 
 module Polyrun
   module Coverage
-    # Rails integration entry point for {Collector.start!}: optional +config/polyrun_coverage.yml+ under the project
-    # root, root inference from +spec_helper.rb+ / +rails_helper.rb+ / +test_helper.rb+, and +report_formats+ for
-    # {Formatter.multi}. Call at the **top** of +spec/spec_helper.rb+ (before +require "rails"+) so stdlib
-    # +Coverage+ sees application code.
+    # Rails integration entry point for {Collector.start!}: coverage settings from
+    # +config/polyrun_coverage.yml+ and/or inline +coverage:+ in +polyrun.yml+ (see {ConfigResolve}),
+    # root inference from +spec_helper.rb+ / +rails_helper.rb+ / +test_helper.rb+, and +report_formats+
+    # for {Formatter.multi}. Call at the **top** of +spec/spec_helper.rb+ (before +require "rails"+) so
+    # stdlib +Coverage+ sees application code.
     #
     #   require "polyrun/coverage/rails"
     #   Polyrun::Coverage::Rails.start!
@@ -16,10 +18,10 @@ module Polyrun
     module Rails
       module_function
 
-      DEFAULT_CONFIG_RELATIVE = File.join("config", "polyrun_coverage.yml").freeze
+      DEFAULT_CONFIG_RELATIVE = ConfigResolve::DEFAULT_FILE
 
       # @param root [String, nil] project root (default: infer from caller, or +Rails.root+ when already loaded)
-      # @param config_path [String, nil] YAML path (default: +<root>/config/polyrun_coverage.yml+ if present)
+      # @param config_path [String, nil] YAML path (default: resolve via {ConfigResolve})
       # @param overrides [Hash] merged over YAML; keys match {Collector.start!} (+report_formats+ builds +formatter+)
       def start!(root: nil, config_path: nil, **overrides)
         return if Collector.disabled?
@@ -29,6 +31,7 @@ module Polyrun
         cfg = load_config(root, config_path)
         merged = deep_merge_hashes(cfg, stringify_keys(overrides))
         merged["root"] = root
+        ConfigResolve::META_KEYS.each { |k| merged.delete(k) }
 
         report_formats = merged.delete("report_formats")
         unless merged.key?("formatter") || report_formats.nil?
@@ -63,12 +66,7 @@ module Polyrun
       end
 
       def load_config(root, config_path)
-        path = config_path || File.join(root, DEFAULT_CONFIG_RELATIVE)
-        path = File.expand_path(path)
-        return {} unless File.file?(path)
-
-        data = YAML.safe_load_file(path, permitted_classes: [Symbol], aliases: true)
-        data.is_a?(Hash) ? stringify_keys(data) : {}
+        ConfigResolve.load(root: root, config_path: config_path)
       end
 
       def build_formatter(formats, root, merged)

data/lib/polyrun/templates/rails_prepare.polyrun.yml

@@ -3,6 +3,8 @@
 # Gate per-worker duplicate work in application code when POLYRUN_SHARD_TOTAL > 1.
 # See: docs/SETUP_PROFILE.md
 
+version: 1
+
 partition:
   paths_file: spec/spec_paths.txt
   shard_total: 5
@@ -17,8 +19,19 @@ prepare:
   rails_root: .
   command: bundle exec ruby bin/test_prepare.rb
 
+start:
+  prepare: true
+  databases: true
+
+# Optional suite hooks (uncomment and set commands):
+# hooks:
+#   before_suite: bundle exec ruby script/polyrun_before_suite.rb
+#   after_suite: bundle exec ruby script/polyrun_after_suite.rb
+hooks: {}
+
 # Optional reporting (see docs/SPEC_QUALITY.md):
 # reporting:
+#   merge_failures: true
 #   merge_spec_quality: true
 #   merge_spec_quality_output: coverage/polyrun-spec-quality.json
 

data/lib/polyrun/templates/rails_prepare_task.rake

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+# Generated by: polyrun init --profile rails-prepare-task
+# Runs once before parallel workers. Skip: POLYRUN_SKIP_PREPARE=1 (legacy: POLYRUN_START_SKIP_PREPARE=1).
+
+namespace :polyrun do
+  desc "One-shot Polyrun prepare (delegates to `polyrun prepare`)"
+  task prepare: :environment do
+    skip = %w[1 true yes].include?(ENV["POLYRUN_SKIP_PREPARE"].to_s.downcase) ||
+      %w[1 true yes].include?(ENV["POLYRUN_START_SKIP_PREPARE"].to_s.downcase)
+    next if skip
+
+    ok = system({"RUBYOPT" => nil}, "bundle", "exec", "polyrun", "prepare")
+    abort "polyrun prepare failed" unless ok
+  end
+end

data/lib/polyrun/version.rb

@@ -1,3 +1,3 @@
 module Polyrun
-  VERSION = "2.2.7"
+  VERSION = "2.2.8"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: polyrun
 version: !ruby/object:Gem::Version
-  version: 2.2.7
+  version: 2.2.8
 platform: ruby
 authors:
 - Andrei Makarov
@@ -222,6 +222,7 @@ files:
 - lib/polyrun/cli/coverage_merge_io.rb
 - lib/polyrun/cli/database_commands.rb
 - lib/polyrun/cli/default_run.rb
+- lib/polyrun/cli/doctor_command.rb
 - lib/polyrun/cli/env_commands.rb
 - lib/polyrun/cli/failure_commands.rb
 - lib/polyrun/cli/help.rb
@@ -244,17 +245,22 @@ files:
 - lib/polyrun/cli/run_shards_planning.rb
 - lib/polyrun/cli/run_shards_run.rb
 - lib/polyrun/cli/run_shards_worker_interrupt.rb
+- lib/polyrun/cli/skip_env.rb
 - lib/polyrun/cli/spec_quality_commands.rb
 - lib/polyrun/cli/start_bootstrap.rb
 - lib/polyrun/cli/timing_command.rb
+- lib/polyrun/cli/validate_command.rb
 - lib/polyrun/config.rb
 - lib/polyrun/config/dotted_path.rb
 - lib/polyrun/config/effective.rb
 - lib/polyrun/config/resolver.rb
+- lib/polyrun/config/schema.rb
+- lib/polyrun/config/suite.rb
 - lib/polyrun/coverage/cobertura_zero_lines.rb
 - lib/polyrun/coverage/collector.rb
 - lib/polyrun/coverage/collector_finish.rb
 - lib/polyrun/coverage/collector_fragment_meta.rb
+- lib/polyrun/coverage/config_resolve.rb
 - lib/polyrun/coverage/example_diff.rb
 - lib/polyrun/coverage/example_diff_snapshot.rb
 - lib/polyrun/coverage/example_diff_track_filter.rb
@@ -360,6 +366,7 @@ files:
 - lib/polyrun/templates/polyrun_hooks_spec_quality.rb
 - lib/polyrun/templates/polyrun_spec_quality.yml
 - lib/polyrun/templates/rails_prepare.polyrun.yml
+- lib/polyrun/templates/rails_prepare_task.rake
 - lib/polyrun/timing/merge.rb
 - lib/polyrun/timing/rspec_example_formatter.rb
 - lib/polyrun/timing/stats.rb