polyrun 1.0.0 → 1.2.0

data/lib/polyrun/cli/prepare_recipe.rb

@@ -1,4 +1,4 @@
-require "open3"
+require_relative "../process_stdio"
 
 module Polyrun
   class CLI
@@ -22,8 +22,7 @@ module Polyrun
           return [manifest, nil]
         end
         if custom && !custom.to_s.strip.empty?
-          _out, err, st = Open3.capture3(*([child_env].compact + ["sh", "-c", custom.to_s]), chdir: rails_root)
-          prepare_log_stderr(err)
+          st = prepare_run_shell_inherit_stdio(child_env, custom.to_s, rails_root, silent: !@verbose)
           unless st.success?
             Polyrun::Log.warn "polyrun prepare: assets custom command failed (exit #{st.exitstatus})"
             return [manifest, 1]
@@ -59,8 +58,7 @@ module Polyrun
           return [manifest, nil]
         end
         lines.each_with_index do |line, i|
-          _out, err, st = Open3.capture3(*([child_env].compact + ["sh", "-c", line]), chdir: rails_root)
-          prepare_log_stderr(err)
+          st = prepare_run_shell_inherit_stdio(child_env, line, rails_root, silent: !@verbose)
           unless st.success?
             Polyrun::Log.warn "polyrun prepare: shell step #{i + 1} failed (exit #{st.exitstatus})"
             return [manifest, 1]
@@ -69,8 +67,15 @@ module Polyrun
         [manifest, nil]
       end
 
-      def prepare_log_stderr(err)
-        Polyrun::Log.warn err unless err.to_s.empty?
+      def prepare_run_shell_inherit_stdio(child_env, script, rails_root, silent: false)
+        Polyrun::ProcessStdio.inherit_stdio_spawn_wait(
+          child_env,
+          "sh",
+          "-c",
+          script.to_s,
+          chdir: rails_root,
+          silent: silent
+        )
       end
     end
   end

data/lib/polyrun/cli/queue_command.rb

@@ -11,6 +11,7 @@ module Polyrun
         dir = ".polyrun-queue"
         paths_file = nil
         timing_path = nil
+        timing_granularity = nil
         worker = ENV["USER"] || "worker"
         batch = 5
         lease_id = nil
@@ -19,7 +20,7 @@ module Polyrun
         Polyrun::Debug.log("queue: subcommand=#{sub.inspect}")
         case sub
         when "init"
-          queue_cmd_init(argv, dir, paths_file, timing_path)
+          queue_cmd_init(argv, dir, paths_file, timing_path, timing_granularity)
         when "claim"
           queue_cmd_claim(argv, dir, worker, batch)
         when "ack"
@@ -32,29 +33,38 @@ module Polyrun
         end
       end
 
-      def queue_cmd_init(argv, dir, paths_file, timing_path)
+      def queue_cmd_init(argv, dir, paths_file, timing_path, timing_granularity)
         OptionParser.new do |opts|
-          opts.banner = "usage: polyrun queue init --paths-file P [--timing PATH] [--dir DIR]"
+          opts.banner = "usage: polyrun queue init --paths-file P [--timing PATH] [--timing-granularity VAL] [--dir DIR]"
           opts.on("--dir PATH") { |v| dir = v }
           opts.on("--paths-file PATH") { |v| paths_file = v }
           opts.on("--timing PATH") { |v| timing_path = v }
+          opts.on("--timing-granularity VAL") { |v| timing_granularity = v }
         end.parse!(argv)
         unless paths_file
           Polyrun::Log.warn "queue init: need --paths-file"
           return 2
         end
+        cfg = Polyrun::Config.load(path: ENV["POLYRUN_CONFIG"])
+        g = resolve_partition_timing_granularity(cfg.partition, timing_granularity)
         items = Polyrun::Partition::Paths.read_lines(paths_file)
-        costs = timing_path ? Polyrun::Partition::Plan.load_timing_costs(File.expand_path(timing_path, Dir.pwd)) : nil
-        ordered = queue_init_ordered_items(items, costs)
+        costs =
+          if timing_path
+            Polyrun::Partition::Plan.load_timing_costs(
+              File.expand_path(timing_path, Dir.pwd),
+              granularity: g
+            )
+          end
+        ordered = queue_init_ordered_items(items, costs, g)
         Polyrun::Queue::FileStore.new(dir).init!(ordered)
         Polyrun::Log.puts JSON.generate({"dir" => File.expand_path(dir), "count" => ordered.size})
         0
       end
 
-      def queue_init_ordered_items(items, costs)
+      def queue_init_ordered_items(items, costs, granularity = :file)
         if costs && !costs.empty?
           dw = costs.values.sum / costs.size.to_f
-          items.sort_by { |p| [-queue_weight_for(p, costs, dw), p] }
+          items.sort_by { |p| [-queue_weight_for(p, costs, dw, granularity: granularity), p] }
         else
           items.sort
         end

data/lib/polyrun/cli/run_shards_command.rb

@@ -12,9 +12,7 @@ module Polyrun
 
       private
 
-      # Default and upper bound for parallel OS processes (POLYRUN_WORKERS / --workers).
-      DEFAULT_PARALLEL_WORKERS = 5
-      MAX_PARALLEL_WORKERS = 10
+      # Default and upper bound for parallel OS processes (POLYRUN_WORKERS / --workers); see {Polyrun::Config}.
 
       # Spawns N OS processes (not Ruby threads) with POLYRUN_SHARD_INDEX / POLYRUN_SHARD_TOTAL so
       # {Coverage::Collector} writes coverage/polyrun-fragment-<shard>.json. Merge with merge-coverage.
@@ -37,6 +35,54 @@ module Polyrun
         cmd_run_shards(combined, config_path)
       end
 
+      # Same as parallel-rspec but runs +bundle exec rails test+ or +bundle exec ruby -I test+ after +--+.
+      def cmd_parallel_minitest(argv, config_path)
+        cfg = Polyrun::Config.load(path: config_path || ENV["POLYRUN_CONFIG"])
+        code = start_bootstrap!(cfg, argv, config_path)
+        return code if code != 0
+
+        sep = argv.index("--")
+        combined =
+          if sep
+            head = argv[0...sep]
+            tail = argv[sep..]
+            head + ["--merge-coverage"] + tail
+          else
+            argv + ["--merge-coverage", "--"] + minitest_parallel_cmd
+          end
+        Polyrun::Debug.log_kv(parallel_minitest: "combined argv", argv: combined)
+        cmd_run_shards(combined, config_path)
+      end
+
+      # Same as parallel-rspec but runs +bundle exec polyrun quick+ after +--+ (one Quick process per shard).
+      # Run from the app root with +bundle exec+ so workers resolve the same gem as the parent (same concern as +bundle exec rspec+).
+      def cmd_parallel_quick(argv, config_path)
+        cfg = Polyrun::Config.load(path: config_path || ENV["POLYRUN_CONFIG"])
+        code = start_bootstrap!(cfg, argv, config_path)
+        return code if code != 0
+
+        sep = argv.index("--")
+        combined =
+          if sep
+            head = argv[0...sep]
+            tail = argv[sep..]
+            head + ["--merge-coverage"] + tail
+          else
+            argv + ["--merge-coverage", "--", "bundle", "exec", "polyrun", "quick"]
+          end
+        Polyrun::Debug.log_kv(parallel_quick: "combined argv", argv: combined)
+        cmd_run_shards(combined, config_path)
+      end
+
+      def minitest_parallel_cmd
+        rails_bin = File.expand_path("bin/rails", Dir.pwd)
+        if File.file?(rails_bin)
+          ["bundle", "exec", "rails", "test"]
+        else
+          ["bundle", "exec", "ruby", "-I", "test"]
+        end
+      end
+
       # Convenience alias: optional legacy script/build_spec_paths.rb (if present and partition.paths_build unset), then parallel-rspec.
       def cmd_start(argv, config_path)
         cfg = Polyrun::Config.load(path: config_path || ENV["POLYRUN_CONFIG"])

data/lib/polyrun/cli/run_shards_plan_boot_phases.rb

@@ -25,16 +25,16 @@ module Polyrun
       end
 
       def run_shards_plan_phase_b(o, cmd, cfg, pc, run_t0, config_path)
-        items, paths_source, err = run_shards_resolve_items(o[:paths_file])
+        items, paths_source, err = run_shards_resolve_items(o[:paths_file], pc)
         return [err, nil] if err
 
-        costs, strategy, err = run_shards_resolve_costs(o[:timing_path], o[:strategy])
+        costs, strategy, err = run_shards_resolve_costs(o[:timing_path], o[:strategy], o[:timing_granularity])
         return [err, nil] if err
 
         run_shards_plan_ready_log(o, strategy, cmd, paths_source, items.size)
 
         constraints = load_partition_constraints(pc, o[:constraints_path])
-        plan = run_shards_make_plan(items, o[:workers], strategy, o[:seed], costs, constraints)
+        plan = run_shards_make_plan(items, o[:workers], strategy, o[:seed], costs, constraints, o[:timing_granularity])
 
         run_shards_debug_shard_sizes(plan, o[:workers])
         Polyrun::Log.warn "polyrun run-shards: #{items.size} paths → #{o[:workers]} workers (#{strategy})" if @verbose

data/lib/polyrun/cli/run_shards_plan_options.rb

@@ -9,17 +9,19 @@ module Polyrun
         st = run_shards_plan_options_state(pc)
         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)
         {
-          workers: env_int("POLYRUN_WORKERS", RunShardsCommand::DEFAULT_PARALLEL_WORKERS),
+          workers: env_int("POLYRUN_WORKERS", Polyrun::Config::DEFAULT_PARALLEL_WORKERS),
           paths_file: nil,
           strategy: (pc["strategy"] || pc[:strategy] || "round_robin").to_s,
           seed: pc["seed"] || pc[:seed],
           timing_path: nil,
           constraints_path: nil,
+          timing_granularity: nil,
           merge_coverage: false,
           merge_output: nil,
           merge_format: nil
@@ -28,18 +30,23 @@ module Polyrun
 
       def run_shards_plan_options_parse!(head, st)
         OptionParser.new do |opts|
-          opts.banner = "usage: polyrun run-shards [--workers N] [--strategy NAME] [--paths-file P] [--timing P] [--constraints P] [--seed S] [--merge-coverage] [--merge-output P] [--merge-format LIST] [--] <command> [args...]"
-          opts.on("--workers N", Integer) { |v| st[:workers] = v }
-          opts.on("--strategy NAME", String) { |v| st[:strategy] = v }
-          opts.on("--seed VAL") { |v| st[:seed] = v }
-          opts.on("--paths-file PATH", String) { |v| st[:paths_file] = v }
-          opts.on("--constraints PATH", String) { |v| st[:constraints_path] = v }
-          opts.on("--timing PATH", "merged polyrun_timing.json; implies cost_binpack unless hrw/cost") { |v| st[:timing_path] = v }
-          opts.on("--merge-coverage", "After success, merge coverage/polyrun-fragment-*.json (Polyrun coverage must be enabled)") { st[:merge_coverage] = true }
-          opts.on("--merge-output PATH", String) { |v| st[:merge_output] = v }
-          opts.on("--merge-format LIST", String) { |v| st[:merge_format] = v }
+          run_shards_plan_options_register!(opts, st)
         end.parse!(head)
       end
+
+      def run_shards_plan_options_register!(opts, st)
+        opts.banner = "usage: polyrun run-shards [--workers N] [--strategy NAME] [--paths-file P] [--timing P] [--timing-granularity VAL] [--constraints P] [--seed S] [--merge-coverage] [--merge-output P] [--merge-format LIST] [--] <command> [args...]"
+        opts.on("--workers N", Integer) { |v| st[:workers] = v }
+        opts.on("--strategy NAME", String) { |v| st[:strategy] = v }
+        opts.on("--seed VAL") { |v| st[:seed] = v }
+        opts.on("--paths-file PATH", String) { |v| st[:paths_file] = v }
+        opts.on("--constraints PATH", String) { |v| st[:constraints_path] = v }
+        opts.on("--timing PATH", "merged polyrun_timing.json; implies cost_binpack unless hrw/cost") { |v| st[:timing_path] = v }
+        opts.on("--timing-granularity VAL", "file (default) or example (experimental)") { |v| st[:timing_granularity] = v }
+        opts.on("--merge-coverage", "After success, merge coverage/polyrun-fragment-*.json (Polyrun coverage must be enabled)") { st[:merge_coverage] = true }
+        opts.on("--merge-output PATH", String) { |v| st[:merge_output] = v }
+        opts.on("--merge-format LIST", String) { |v| st[:merge_format] = v }
+      end
     end
   end
 end

data/lib/polyrun/cli/run_shards_planning.rb

@@ -38,9 +38,9 @@ module Polyrun
           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
+        if w > Polyrun::Config::MAX_PARALLEL_WORKERS
+          Polyrun::Log.warn "polyrun run-shards: capping --workers / POLYRUN_WORKERS from #{w} to #{Polyrun::Config::MAX_PARALLEL_WORKERS}"
+          o[:workers] = Polyrun::Config::MAX_PARALLEL_WORKERS
         end
         nil
       end
@@ -53,26 +53,29 @@ module Polyrun
         nil
       end
 
-      def run_shards_resolve_items(paths_file)
-        resolved = Polyrun::Partition::Paths.resolve_run_shard_items(paths_file: paths_file)
+      def run_shards_resolve_items(paths_file, partition)
+        resolved = Polyrun::Partition::Paths.resolve_run_shard_items(paths_file: paths_file, partition: partition)
         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}"
+        Polyrun::Log.warn "polyrun run-shards: #{items.size} 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)"
+          Polyrun::Log.warn "polyrun run-shards: no paths (empty paths file or list)"
           return [nil, nil, 2]
         end
         [items, paths_source, nil]
       end
 
-      def run_shards_resolve_costs(timing_path, strategy)
+      def run_shards_resolve_costs(timing_path, strategy, timing_granularity)
         if timing_path
-          costs = Polyrun::Partition::Plan.load_timing_costs(File.expand_path(timing_path.to_s, Dir.pwd))
+          costs = Polyrun::Partition::Plan.load_timing_costs(
+            File.expand_path(timing_path.to_s, Dir.pwd),
+            granularity: timing_granularity
+          )
           if costs.empty?
             Polyrun::Log.warn "polyrun run-shards: timing file missing or empty: #{timing_path}"
             return [nil, nil, 2]
@@ -90,7 +93,7 @@ module Polyrun
         end
       end
 
-      def run_shards_make_plan(items, workers, strategy, seed, costs, constraints)
+      def run_shards_make_plan(items, workers, strategy, seed, costs, constraints, timing_granularity)
         Polyrun::Debug.time("Partition::Plan.new (partition #{items.size} paths → #{workers} shards)") do
           Polyrun::Partition::Plan.new(
             items: items,
@@ -99,7 +102,8 @@ module Polyrun
             seed: seed,
             costs: costs,
             constraints: constraints,
-            root: Dir.pwd
+            root: Dir.pwd,
+            timing_granularity: timing_granularity
           )
         end
       end
@@ -115,7 +119,7 @@ module Polyrun
 
       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}
+          polyrun run-shards: #{item_count} path(s) -> #{workers} parallel worker processes (not Ruby threads); strategy=#{strategy}
           (plain `bundle exec rspec` is one process; this command fans out.)
         MSG
       end

data/lib/polyrun/cli/start_bootstrap.rb

@@ -4,10 +4,6 @@ module Polyrun
     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"
@@ -76,7 +72,7 @@ module Polyrun
       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)
+        workers = env_int("POLYRUN_WORKERS", Polyrun::Config::DEFAULT_PARALLEL_WORKERS)
         i = 0
         while i < head.size
           if head[i] == "--workers" && head[i + 1]
@@ -87,7 +83,7 @@ module Polyrun
             i += 1
           end
         end
-        workers.clamp(1, START_ARG_WORKERS_MAX)
+        workers.clamp(1, Polyrun::Config::MAX_PARALLEL_WORKERS)
       end
 
       def truthy_env?(name)

data/lib/polyrun/cli.rb

@@ -12,9 +12,30 @@ require_relative "cli/queue_command"
 require_relative "cli/timing_command"
 require_relative "cli/init_command"
 require_relative "cli/quick_command"
+require_relative "cli/ci_shard_run_command"
+require_relative "cli/config_command"
+require_relative "cli/default_run"
+require_relative "cli/help"
 
 module Polyrun
   class CLI
+    CI_SHARD_COMMANDS = {
+      "ci-shard-run" => :cmd_ci_shard_run,
+      "ci-shard-rspec" => :cmd_ci_shard_rspec
+    }.freeze
+
+    # Keep in sync with +dispatch_cli_command_subcommands+ (+when+ branches). Used for implicit path routing.
+    DISPATCH_SUBCOMMAND_NAMES = %w[
+      plan prepare merge-coverage report-coverage report-junit report-timing
+      env config merge-timing db:setup-template db:setup-shard db:clone-shards
+      run-shards parallel-rspec start build-paths init queue quick
+    ].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.
+    IMPLICIT_PATH_EXCLUSION_TOKENS = (
+      DISPATCH_SUBCOMMAND_NAMES + CI_SHARD_COMMANDS.keys + %w[help version]
+    ).freeze
+
     include Helpers
     include PlanCommand
     include PrepareCommand
@@ -27,6 +48,10 @@ module Polyrun
     include TimingCommand
     include InitCommand
     include QuickCommand
+    include CiShardRunCommand
+    include ConfigCommand
+    include DefaultRun
+    include Help
 
     def self.run(argv = ARGV)
       new.run(argv)
@@ -37,12 +62,30 @@ module Polyrun
       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
+      if argv.empty?
+        Polyrun::Debug.log_kv(
+          command: "(default)",
+          cwd: Dir.pwd,
+          polyrun_config: config_path,
+          argv_rest: [],
+          verbose: @verbose
+        )
+        return dispatch_default_parallel!(config_path)
+      end
+
+      if implicit_parallel_run?(argv)
+        Polyrun::Debug.log_kv(
+          command: "(paths)",
+          cwd: Dir.pwd,
+          polyrun_config: config_path,
+          argv_rest: argv.dup,
+          verbose: @verbose
+        )
+        return dispatch_implicit_parallel_targets!(argv, config_path)
       end
 
+      command = argv.shift
+
       Polyrun::Debug.log_kv(
         command: command,
         cwd: Dir.pwd,
@@ -89,6 +132,7 @@ module Polyrun
       end
     end
 
+    # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity -- explicit dispatch table
     def dispatch_cli_command_subcommands(command, argv, config_path)
       case command
       when "plan"
@@ -105,6 +149,8 @@ module Polyrun
         cmd_report_timing(argv)
       when "env"
         cmd_env(argv, config_path)
+      when "config"
+        cmd_config(argv, config_path)
       when "merge-timing"
         cmd_merge_timing(argv)
       when "db:setup-template"
@@ -121,6 +167,8 @@ module Polyrun
         cmd_start(argv, config_path)
       when "build-paths"
         cmd_build_paths(config_path)
+      when *CI_SHARD_COMMANDS.keys
+        send(CI_SHARD_COMMANDS.fetch(command), argv, config_path)
       when "init"
         cmd_init(argv, config_path)
       when "queue"
@@ -132,49 +180,7 @@ module Polyrun
         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
+    # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity
 
     def cmd_version
       Polyrun::Log.puts "polyrun #{Polyrun::VERSION}"

data/lib/polyrun/config/dotted_path.rb

@@ -0,0 +1,21 @@
+module Polyrun
+  class Config
+    # Read nested keys from loaded YAML (+String+ / +Symbol+ indifferent at each step).
+    module DottedPath
+      module_function
+
+      def dig(raw, dotted)
+        segments = dotted.split(".")
+        return nil if segments.empty?
+        return nil if segments.any?(&:empty?)
+
+        segments.reduce(raw) do |m, seg|
+          break nil if m.nil?
+          break nil unless m.is_a?(Hash)
+
+          m[seg] || m[seg.to_sym]
+        end
+      end
+    end
+  end
+end

data/lib/polyrun/config/effective.rb

@@ -0,0 +1,71 @@
+require_relative "dotted_path"
+require_relative "resolver"
+
+module Polyrun
+  class Config
+    # Nested hash of values Polyrun uses: loaded YAML (string keys) with overlays for
+    # merged +prepare.env+, resolved +partition.shard_index+ / +shard_total+ / +timing_granularity+,
+    # and top-level +workers+ (+POLYRUN_WORKERS+ default).
+    #
+    # +build+ memoizes the last (cfg, env) in-process so repeated +dig+ calls on the same load do not
+    # rebuild the tree (single-threaded CLI).
+    module Effective
+      class << self
+        # Per-thread cache avoids rebuilding the effective tree on repeated +dig+; no class ivars (RuboCop ThreadSafety).
+        def build(cfg, env: ENV)
+          key = cache_key(cfg, env)
+          per_thread = (Thread.current[:polyrun_effective_build] ||= {})
+          per_thread[key] ||= build_uncached(cfg, env: env)
+        end
+
+        def dig(cfg, dotted_path, env: ENV)
+          Polyrun::Config::DottedPath.dig(build(cfg, env: env), dotted_path)
+        end
+
+        private
+
+        def cache_key(cfg, env)
+          [cfg.path, cfg.object_id, env_fingerprint(env)]
+        end
+
+        def env_fingerprint(env)
+          env.to_h.keys.sort.map { |k| [k, env[k]] }.hash
+        end
+
+        def build_uncached(cfg, env:)
+          r = Polyrun::Config::Resolver
+          base = deep_stringify_keys(cfg.raw)
+
+          prep = cfg.prepare
+          base["prepare"] = deep_stringify_keys(prep)
+          base["prepare"]["env"] = r.merged_prepare_env(prep, env)
+
+          pc = cfg.partition
+          part = deep_stringify_keys(pc).merge(
+            "shard_index" => r.resolve_shard_index(pc, env),
+            "shard_total" => r.resolve_shard_total(pc, env),
+            "timing_granularity" => r.resolve_partition_timing_granularity(pc, nil, env).to_s
+          )
+          base["partition"] = part
+
+          base["workers"] = r.parallel_worker_count_default(env)
+
+          base
+        end
+
+        def deep_stringify_keys(obj)
+          case obj
+          when Hash
+            obj.each_with_object({}) do |(k, v), m|
+              m[k.to_s] = deep_stringify_keys(v)
+            end
+          when Array
+            obj.map { |e| deep_stringify_keys(e) }
+          else
+            obj
+          end
+        end
+      end
+    end
+  end
+end

data/lib/polyrun/config/resolver.rb

@@ -0,0 +1,70 @@
+require_relative "../env/ci"
+require_relative "../partition/timing_keys"
+
+module Polyrun
+  class Config
+    # Single source for values derived from +polyrun.yml+, +ENV+, and CI detection.
+    # Used by {Effective}, CLI helpers, and prepare.
+    module Resolver
+      module_function
+
+      def env_int(name, fallback, env = ENV)
+        s = env[name]
+        return fallback if s.nil? || s.empty?
+
+        Integer(s, exception: false) || fallback
+      end
+
+      def prepare_env_yaml_string_map(prep)
+        (prep["env"] || prep[:env] || {}).transform_keys(&:to_s).transform_values(&:to_s)
+      end
+
+      # Same merge order as +polyrun prepare+: YAML +prepare.env+ overrides process +ENV+ for overlapping keys.
+      def merged_prepare_env(prep, env = ENV)
+        prep_env = prepare_env_yaml_string_map(prep)
+        env.to_h.merge(prep_env)
+      end
+
+      def partition_int(pc, keys, default)
+        keys.each do |k|
+          v = pc[k] || pc[k.to_sym]
+          next if v.nil? || v.to_s.empty?
+
+          i = Integer(v, exception: false)
+          return i unless i.nil?
+        end
+        default
+      end
+
+      def resolve_shard_index(pc, env = ENV)
+        return Integer(env["POLYRUN_SHARD_INDEX"]) if env["POLYRUN_SHARD_INDEX"] && !env["POLYRUN_SHARD_INDEX"].empty?
+
+        ci = Polyrun::Env::Ci.detect_shard_index
+        return ci unless ci.nil?
+
+        partition_int(pc, %w[shard_index shard], 0)
+      end
+
+      def resolve_shard_total(pc, env = ENV)
+        return Integer(env["POLYRUN_SHARD_TOTAL"]) if env["POLYRUN_SHARD_TOTAL"] && !env["POLYRUN_SHARD_TOTAL"].empty?
+
+        ci = Polyrun::Env::Ci.detect_shard_total
+        return ci unless ci.nil?
+
+        partition_int(pc, %w[shard_total total], 1)
+      end
+
+      # +cli_val+ is an override (e.g. +run-shards --timing-granularity+); +nil+ uses YAML then +POLYRUN_TIMING_GRANULARITY+.
+      def resolve_partition_timing_granularity(pc, cli_val, env = ENV)
+        raw = cli_val
+        raw ||= pc && (pc["timing_granularity"] || pc[:timing_granularity])
+        raw ||= env["POLYRUN_TIMING_GRANULARITY"]
+        Polyrun::Partition::TimingKeys.normalize_granularity(raw || "file")
+      end
+
+      def parallel_worker_count_default(env = ENV)
+        env_int("POLYRUN_WORKERS", Polyrun::Config::DEFAULT_PARALLEL_WORKERS, env)
+      end
+    end
+  end
+end