polyrun 1.1.0 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 65a84fc362b402e23a550b5ea4f9980a5f6fc896fb5d1c445c3c8d2b22849604
-  data.tar.gz: 55c8baa0261b1e012c5b82592c82ae68409481eb7bee01503a0408d7b837fafe
+  metadata.gz: 5dd8b178e07e0cf6648284d59d5b8f58a5feceeb2c7570edfd381aafaed207cb
+  data.tar.gz: cd2846dc77b56bccf0ac411fcc4f6a2a7aaf2e106609172e84299c2a1d253f64
 SHA512:
-  metadata.gz: 50b5673497a1454363faf29781f9c5fc6f231cb5e8f85b570da61e036af3cb78450e2b6dc4854db1fe99528c292fece8f022c4e6cf69638bc8c09881fdb63a18
-  data.tar.gz: b10cf9ec6d80d0aeecfda0965ec6d7473d4c69a70a520bb3fb5b911679a0ba00d28be163f90458b7d4c3f5a62aa1de94739fb70811a5e82fe136651ca2c07c14
+  metadata.gz: c9a71f317d28ce3dcdf25d9c8e08221e71eadb2cf044217170ca0ba08cdc22cb702e6adaf02383d4e6089fa2fdddc94198cc420f031f53186715b67c14c92567
+  data.tar.gz: 81469ea975e78befbf6c66e3482e5c6006c11bb8b1806a079545a00ac057f250d49323aeab6685e8eaec22ff65e5aa72fb28aaca688365048483650d3c78de00

data/CHANGELOG.md

@@ -1,5 +1,17 @@
 # CHANGELOG
 
+## 1.2.0 (2026-04-15)
+
+- Add `polyrun config <dotted.path>` to print values from `Polyrun::Config::Effective` (same effective tree as runtime: arbitrary YAML paths, merged `prepare.env.<KEY>` as for `polyrun prepare`, resolved `partition.shard_index`, `partition.shard_total`, `partition.timing_granularity`, and `workers`).
+- Memoize `Polyrun::Config::Effective.build` per thread (keyed by config path, object id, and env fingerprint) so repeated `dig` calls do not rebuild the merged tree.
+- Add `DISPATCH_SUBCOMMAND_NAMES` and `IMPLICIT_PATH_EXCLUSION_TOKENS`; route implicit path-only argv against one list (includes `ci-shard-*`, `help`, `version`); add spec that dispatch names match `when` branches in `lib/polyrun/cli.rb`.
+- Run `polyrun` with no subcommand to fan out parallel tests: pick RSpec (`start`), Minitest (`bundle exec rails test` or `bundle exec ruby -I test`), or Polyrun Quick (`bundle exec polyrun quick`) from `spec/**/*_spec.rb` vs `test/**/*_test.rb` vs Quick globs.
+- Accept path-only argv (and optional `run-shards` options before paths, e.g. `--workers`) to shard those files without naming a subcommand; infer suite from `_spec.rb` / `_test.rb` vs other `.rb` files.
+- Add optional `partition.suite` (`auto`, `rspec`, `minitest`, `quick`) when resolving globbed paths for `run-shards` / `parallel-rspec` / default runs.
+- Document implicit argv (known subcommand first vs path-like implicit parallel) and parallel Quick `bundle exec` from app root in `polyrun help` and `examples/README.md`.
+- Comment `detect_auto_suite` glob order in `lib/polyrun/partition/paths.rb` (RSpec/Minitest globs before Quick discovery).
+- Remove redundant `OptionParser` from `polyrun config` (no options; banner only).
+
 ## 1.1.0 (2026-04-15)
 
 - Add `ci-shard-run` / `ci-shard-rspec` for matrix-style sharding (one job per `POLYRUN_SHARD_INDEX` / `POLYRUN_SHARD_TOTAL`): resolve paths via the same plan as `polyrun plan`, then `exec` the given command with this shard’s paths (unlike `run-shards`, which fans out multiple workers on one host).

data/README.md

@@ -19,7 +19,7 @@ Capybara and Playwright stay in your application; Polyrun does not replace brows
 
 ## How?
 
-1. Add the gem (path or RubyGems) and `require "polyrun"` where you integrate—for example coverage merge in CI or prepare hooks.
+1. Add the gem (path or RubyGems) and `require "polyrun"` where you integrate—for example coverage merge in CI or prepare hooks. To pin the executable in your app, run `bundle binstubs polyrun` (writes `bin/polyrun`; ensure `bin/` is on `PATH` or invoke `./bin/polyrun`).
 2. Add a `polyrun.yml` beside the app, or pass `-c` to point at one. Configure `partition` (paths, shard index and total, strategy), and optionally `databases` (Postgres template and `shard_db_pattern`), `prepare`, and `coverage`. If you use `partition.paths_build`, Polyrun can write `partition.paths_file` (for example `spec/spec_paths.txt`) from globs and ordered stages—substring priorities for integration specs, or a regex stage for “Rails-heavy files first”—without a per-project Ruby script. That step runs before `plan` and `run-shards`. Use `bin/polyrun build-paths` to refresh the paths file only.
 3. Run prepare once before fan-out—for example `script/ci_prepare` for Vite or webpack builds, and `Polyrun::Prepare::Assets` digest markers. See `examples/TESTING_REQUIREMENTS.md`.
 4. Run workers with `bin/polyrun run-shards --workers N -- bundle exec rspec`: N separate OS processes, each running RSpec with its own file list from `partition.paths_file`, or `spec/spec_paths.txt`, or else `spec/**/*_spec.rb`. Stderr shows where paths came from; after a successful multi-worker run it reminds you to run merge-coverage unless you use `parallel-rspec` or `run-shards --merge-coverage`.

data/lib/polyrun/cli/config_command.rb

@@ -0,0 +1,42 @@
+require "json"
+
+require_relative "../config/effective"
+
+module Polyrun
+  class CLI
+    module ConfigCommand
+      private
+
+      def cmd_config(argv, config_path)
+        dotted = argv.shift
+        if dotted.nil? || dotted.strip.empty?
+          Polyrun::Log.warn "polyrun config: need a dotted path (e.g. prepare.env.PLAYWRIGHT_ENV, partition.paths_file, workers)"
+          return 2
+        end
+        unless argv.empty?
+          Polyrun::Log.warn "polyrun config: unexpected arguments: #{argv.join(" ")}"
+          return 2
+        end
+
+        cfg = Polyrun::Config.load(path: config_path || ENV["POLYRUN_CONFIG"])
+        val = Polyrun::Config::Effective.dig(cfg, dotted)
+        if val.nil?
+          Polyrun::Log.warn "polyrun config: no value for #{dotted}"
+          return 1
+        end
+
+        Polyrun::Log.puts format_config_value(val)
+        0
+      end
+
+      def format_config_value(val)
+        case val
+        when Hash, Array
+          JSON.generate(val)
+        else
+          val.to_s
+        end
+      end
+    end
+  end
+end

data/lib/polyrun/cli/default_run.rb

@@ -0,0 +1,115 @@
+require "tempfile"
+
+module Polyrun
+  class CLI
+    # No-subcommand default (`polyrun`) and path-only argv (implicit parallel run).
+    module DefaultRun
+      private
+
+      def dispatch_default_parallel!(config_path)
+        suite = Polyrun::Partition::Paths.detect_auto_suite(Dir.pwd)
+        unless suite
+          Polyrun::Log.warn "polyrun: no tests found (spec/**/*_spec.rb, test/**/*_test.rb, or Polyrun quick files). See polyrun help."
+          return 2
+        end
+
+        Polyrun::Log.warn "polyrun: default → parallel #{suite} (use `polyrun help` for subcommands)" if @verbose
+
+        case suite
+        when :rspec
+          cmd_start([], config_path)
+        when :minitest
+          cmd_parallel_minitest([], config_path)
+        when :quick
+          cmd_parallel_quick([], config_path)
+        else
+          2
+        end
+      end
+
+      # If +argv[0]+ is in {IMPLICIT_PATH_EXCLUSION_TOKENS}, treat as a normal subcommand. Otherwise, path-like
+      # tokens may trigger implicit parallel sharding (see +print_help+).
+      def implicit_parallel_run?(argv)
+        return false if argv.empty?
+        return false if Polyrun::CLI::IMPLICIT_PATH_EXCLUSION_TOKENS.include?(argv[0])
+
+        argv.any? { |a| cli_implicit_path_token?(a) }
+      end
+
+      def cli_implicit_path_token?(s)
+        return false if s.start_with?("-") && s != "-"
+        return true if s == "-"
+        return true if s.start_with?("./", "../", "/")
+        return true if s.end_with?(".rb")
+        return true if File.exist?(File.expand_path(s))
+        return true if /[*?\[]/.match?(s)
+
+        false
+      end
+
+      def dispatch_implicit_parallel_targets!(argv, config_path)
+        path_tokens = argv.select { |a| cli_implicit_path_token?(a) }
+        head = argv.reject { |a| cli_implicit_path_token?(a) }
+        expanded = expand_implicit_target_paths(path_tokens)
+        if expanded.empty?
+          Polyrun::Log.warn "polyrun: no files matched path arguments"
+          return 2
+        end
+
+        suite = Polyrun::Partition::Paths.infer_suite_from_paths(expanded)
+        if suite == :invalid
+          Polyrun::Log.warn "polyrun: mixing _spec.rb and _test.rb paths in one run is not supported"
+          return 2
+        end
+        if suite.nil?
+          Polyrun::Log.warn "polyrun: could not infer suite from paths"
+          return 2
+        end
+
+        tmp = Tempfile.new(["polyrun-paths-", ".txt"])
+        begin
+          tmp.write(expanded.join("\n") + "\n")
+          tmp.close
+          combined = head + ["--paths-file", tmp.path]
+          case suite
+          when :rspec
+            cmd_start(combined, config_path)
+          when :minitest
+            cmd_parallel_minitest(combined, config_path)
+          when :quick
+            cmd_parallel_quick(combined, config_path)
+          else
+            2
+          end
+        ensure
+          tmp.close! unless tmp.closed?
+          begin
+            File.unlink(tmp.path)
+          rescue Errno::ENOENT
+            # already removed
+          end
+        end
+      end
+
+      def expand_implicit_target_paths(path_tokens)
+        path_tokens.flat_map do |p|
+          abs = File.expand_path(p)
+          if File.directory?(abs)
+            spec = Dir.glob(File.join(abs, "**", "*_spec.rb")).sort
+            test = Dir.glob(File.join(abs, "**", "*_test.rb")).sort
+            quick = Dir.glob(File.join(abs, "**", "*.rb")).sort.reject do |f|
+              File.basename(f).end_with?("_spec.rb", "_test.rb")
+            end
+            spec + test + quick
+          elsif /[*?\[]/.match?(p)
+            Dir.glob(abs).sort
+          elsif File.file?(abs)
+            [abs]
+          else
+            []
+          end
+        end.uniq
+      end
+    end
+  end
+end

data/lib/polyrun/cli/help.rb

@@ -0,0 +1,54 @@
+module Polyrun
+  class CLI
+    module Help
+      def print_help
+        Polyrun::Log.puts <<~HELP
+          usage: polyrun [global options] [<command> | <paths...>]
+
+          With no command, runs parallel tests for the detected suite: RSpec under spec/, Minitest under test/, or Polyrun Quick (same discovery as polyrun quick). If the first argument is a known subcommand name, it is dispatched. Otherwise, path-like tokens (optionally with run-shards flags such as --workers) shard those files in parallel; see commands below.
+
+          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)
+          Partition timing granularity (default file): POLYRUN_TIMING_GRANULARITY=file|example (experimental per-example; see partition.timing_granularity)
+
+          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
+            ci-shard-run         CI matrix: build-paths + plan for POLYRUN_SHARD_INDEX / POLYRUN_SHARD_TOTAL (or config), then run your command with that shard's paths after -- (like run-shards; not multi-worker)
+            ci-shard-rspec       same as ci-shard-run -- bundle exec rspec; optional -- [rspec-only flags]
+            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
+            config               print effective config by dotted path (see Polyrun::Config::Effective; same tree as YAML plus merged prepare.env, resolved partition shard fields, workers)
+            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
+    end
+  end
+end

data/lib/polyrun/cli/helpers.rb

@@ -7,40 +7,16 @@ module Polyrun
     module Helpers
       private
 
-      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 env_int(name, fallback)
-        s = ENV[name]
-        return fallback if s.nil? || s.empty?
-
-        Integer(s, exception: false) || fallback
+        Polyrun::Config::Resolver.env_int(name, fallback)
       end
 
       def resolve_shard_index(pc)
-        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)
+        Polyrun::Config::Resolver.resolve_shard_index(pc)
       end
 
       def resolve_shard_total(pc)
-        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)
+        Polyrun::Config::Resolver.resolve_shard_total(pc)
       end
 
       def expand_merge_input_pattern(path)
@@ -119,10 +95,7 @@ module Polyrun
 
       # CLI + polyrun.yml + POLYRUN_TIMING_GRANULARITY; default +:file+.
       def resolve_partition_timing_granularity(pc, cli_val)
-        raw = cli_val
-        raw ||= pc && (pc["timing_granularity"] || pc[:timing_granularity])
-        raw ||= ENV["POLYRUN_TIMING_GRANULARITY"]
-        Polyrun::Partition::TimingKeys.normalize_granularity(raw || "file")
+        Polyrun::Config::Resolver.resolve_partition_timing_granularity(pc, cli_val)
       end
     end
   end

data/lib/polyrun/cli/prepare_command.rb

@@ -19,8 +19,8 @@ module Polyrun
         cfg = Polyrun::Config.load(path: config_path || ENV["POLYRUN_CONFIG"])
         prep = cfg.prepare
         recipe = prep["recipe"] || prep[:recipe] || "default"
-        prep_env = (prep["env"] || prep[:env] || {}).transform_keys(&:to_s).transform_values(&:to_s)
-        child_env = prep_env.empty? ? nil : ENV.to_h.merge(prep_env)
+        prep_env = Polyrun::Config::Resolver.prepare_env_yaml_string_map(prep)
+        child_env = prep_env.empty? ? nil : Polyrun::Config::Resolver.merged_prepare_env(prep)
         manifest = prepare_build_manifest(recipe, dry, prep_env)
 
         exit_code = prepare_dispatch_recipe(manifest, prep, recipe, dry, child_env)

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,7 +25,7 @@ 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], o[:timing_granularity])

data/lib/polyrun/cli/run_shards_plan_options.rb

@@ -15,7 +15,7 @@ module Polyrun
 
       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],

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,18 +53,18 @@ 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]
@@ -119,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

@@ -13,6 +13,9 @@ 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
@@ -21,6 +24,18 @@ module Polyrun
       "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
@@ -34,6 +49,9 @@ module Polyrun
     include InitCommand
     include QuickCommand
     include CiShardRunCommand
+    include ConfigCommand
+    include DefaultRun
+    include Help
 
     def self.run(argv = ARGV)
       new.run(argv)
@@ -44,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,
@@ -96,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"
@@ -112,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"
@@ -141,52 +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)
-        Partition timing granularity (default file): POLYRUN_TIMING_GRANULARITY=file|example (experimental per-example; see partition.timing_granularity)
-
-        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
-          ci-shard-run         CI matrix: build-paths + plan for POLYRUN_SHARD_INDEX / POLYRUN_SHARD_TOTAL (or config), then run your command with that shard's paths after -- (like run-shards; not multi-worker)
-          ci-shard-rspec       same as ci-shard-run -- bundle exec rspec; optional -- [rspec-only flags]
-          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

data/lib/polyrun/config.rb

@@ -5,6 +5,10 @@ module Polyrun
   class Config
     DEFAULT_FILENAMES = %w[polyrun.yml config/polyrun.yml].freeze
 
+    # Parallel worker defaults (+run-shards+, +POLYRUN_WORKERS+); single source with {Resolver} and {Effective}.
+    DEFAULT_PARALLEL_WORKERS = 5
+    MAX_PARALLEL_WORKERS = 10
+
     attr_reader :path, :raw
 
     def self.load(path: nil)
@@ -59,3 +63,6 @@ module Polyrun
     end
   end
 end
+
+require_relative "config/resolver"
+require_relative "config/effective"

data/lib/polyrun/partition/paths.rb

@@ -8,9 +8,45 @@ module Polyrun
         File.read(File.expand_path(path.to_s, Dir.pwd)).split("\n").map(&:strip).reject(&:empty?)
       end
 
+      # Prefer +spec/+ RSpec files, then +test/+ Minitest, then Polyrun Quick files (same globs as +polyrun quick+).
+      # Order avoids running the broader Quick glob when RSpec or Minitest files already exist.
+      def detect_auto_suite(cwd = Dir.pwd)
+        base = File.expand_path(cwd)
+        return :rspec if Dir.glob(File.join(base, "spec/**/*_spec.rb")).any?
+
+        return :minitest if Dir.glob(File.join(base, "test/**/*_test.rb")).any?
+
+        quick = quick_parallel_default_paths(base)
+        return :quick if quick.any?
+
+        nil
+      end
+
+      # Infer parallel suite from explicit paths (+_spec.rb+ vs +_test.rb+ vs Polyrun quick-style +.rb+).
+      # Returns +:rspec+, +:minitest+, +:quick+, +:invalid+ (mixed spec and test), or +nil+ (empty).
+      def infer_suite_from_paths(paths)
+        paths = paths.map { |p| File.expand_path(p) }
+        return nil if paths.empty?
+
+        specs = paths.count { |p| File.basename(p).end_with?("_spec.rb") }
+        tests = paths.count { |p| File.basename(p).end_with?("_test.rb") }
+        return :invalid if specs.positive? && tests.positive?
+
+        return :rspec if specs.positive?
+        return :minitest if tests.positive?
+
+        others = paths.size - specs - tests
+        return :quick if others.positive?
+
+        nil
+      end
+
       # When +paths_file+ is set but missing, returns +{ error: "..." }+.
       # Otherwise returns +{ items:, source: }+ (human-readable source label).
-      def resolve_run_shard_items(paths_file: nil, cwd: Dir.pwd)
+      #
+      # +partition.suite+ (optional): +auto+ (default), +rspec+, +minitest+, +quick+ — used only when resolving
+      # from globs (no explicit +paths_file+ and no +spec/spec_paths.txt+).
+      def resolve_run_shard_items(paths_file: nil, cwd: Dir.pwd, partition: {})
         if paths_file
           abs = File.expand_path(paths_file.to_s, cwd)
           unless File.file?(abs)
@@ -20,9 +56,54 @@ module Polyrun
         elsif File.file?(File.join(cwd, "spec", "spec_paths.txt"))
           {items: read_lines(File.join(cwd, "spec", "spec_paths.txt")), source: "spec/spec_paths.txt"}
         else
-          {items: Dir.glob(File.join(cwd, "spec/**/*_spec.rb")).sort, source: "spec/**/*_spec.rb glob"}
+          resolve_run_shard_items_glob(cwd: cwd, partition: partition)
         end
       end
+
+      def resolve_run_shard_items_glob(cwd:, partition: {})
+        suite = (partition["suite"] || partition[:suite] || "auto").to_s.downcase
+        suite = "auto" if suite.empty?
+
+        base = File.expand_path(cwd)
+        spec = Dir.glob(File.join(base, "spec/**/*_spec.rb")).sort
+        test = Dir.glob(File.join(base, "test/**/*_test.rb")).sort
+        quick = quick_parallel_default_paths(base)
+
+        case suite
+        when "rspec"
+          return {error: "partition.suite is rspec but no spec/**/*_spec.rb files"} if spec.empty?
+
+          {items: spec, source: "spec/**/*_spec.rb glob"}
+        when "minitest"
+          return {error: "partition.suite is minitest but no test/**/*_test.rb files"} if test.empty?
+
+          {items: test, source: "test/**/*_test.rb glob"}
+        when "quick"
+          return {error: "partition.suite is quick but no Polyrun quick files under spec/ or test/"} if quick.empty?
+
+          {items: quick, source: "Polyrun quick glob"}
+        when "auto"
+          if spec.any?
+            {items: spec, source: "spec/**/*_spec.rb glob"}
+          elsif test.any?
+            {items: test, source: "test/**/*_test.rb glob"}
+          elsif quick.any?
+            {items: quick, source: "Polyrun quick glob"}
+          else
+            {
+              error: "no spec paths (spec/spec_paths.txt, partition.paths_file, or spec/**/*_spec.rb); " \
+                     "no test/**/*_test.rb; no Polyrun quick files"
+            }
+          end
+        else
+          {error: "unknown partition.suite: #{suite.inspect} (expected auto, rspec, minitest, quick)"}
+        end
+      end
+
+      def quick_parallel_default_paths(base)
+        require_relative "../quick/runner"
+        Polyrun::Quick::Runner.parallel_default_paths(base)
+      end
     end
   end
 end

data/lib/polyrun/quick/runner.rb

@@ -62,6 +62,30 @@ module Polyrun
         new(out: out, err: err, verbose: verbose).run(paths)
       end
 
+      # Files Polyrun::Quick would run with no explicit paths (excludes normal RSpec/Minitest files).
+      def self.parallel_default_paths(cwd = Dir.pwd)
+        base = File.expand_path(cwd)
+        globs = [
+          File.join(base, "spec", "polyrun_quick", "**", "*.rb"),
+          File.join(base, "test", "polyrun_quick", "**", "*.rb"),
+          File.join(base, "spec", "**", "*.rb"),
+          File.join(base, "test", "**", "*.rb")
+        ]
+        globs.flat_map { |g| Dir.glob(g) }.uniq.reject { |p| quick_path_excluded?(p, base) }.sort
+      end
+
+      def self.quick_path_excluded?(path, base)
+        rel = Pathname.new(path).relative_path_from(Pathname.new(base)).to_s
+        parts = rel.split(File::SEPARATOR)
+        bn = File.basename(path)
+        return true if bn.end_with?("_spec.rb", "_test.rb")
+        return true if %w[spec_helper.rb rails_helper.rb test_helper.rb].include?(bn)
+        return true if parts[0] == "spec" && %w[support fixtures factories].include?(parts[1])
+        return true if parts[0] == "test" && %w[support fixtures].include?(parts[1])
+
+        false
+      end
+
       def initialize(out: $stdout, err: $stderr, verbose: false)
         @out = out
         @err = err
@@ -153,27 +177,12 @@ module Polyrun
       end
 
       def default_globs
-        base = File.expand_path(Dir.pwd)
-        globs = [
-          File.join(base, "spec", "polyrun_quick", "**", "*.rb"),
-          File.join(base, "test", "polyrun_quick", "**", "*.rb"),
-          File.join(base, "spec", "**", "*.rb"),
-          File.join(base, "test", "**", "*.rb")
-        ]
-        globs.flat_map { |g| Dir.glob(g) }.uniq.reject { |p| default_quick_exclude?(p, base) }.sort
+        Runner.parallel_default_paths(Dir.pwd)
       end
 
       # Omit RSpec/Minitest files and common helpers so +polyrun quick+ with no args does not load normal suites.
       def default_quick_exclude?(path, base)
-        rel = Pathname.new(path).relative_path_from(Pathname.new(base)).to_s
-        parts = rel.split(File::SEPARATOR)
-        bn = File.basename(path)
-        return true if bn.end_with?("_spec.rb", "_test.rb")
-        return true if %w[spec_helper.rb rails_helper.rb test_helper.rb].include?(bn)
-        return true if parts[0] == "spec" && %w[support fixtures factories].include?(parts[1])
-        return true if parts[0] == "test" && %w[support fixtures].include?(parts[1])
-
-        false
+        Runner.quick_path_excluded?(path, base)
       end
     end
   end

data/lib/polyrun/version.rb

@@ -1,3 +1,3 @@
 module Polyrun
-  VERSION = "1.1.0"
+  VERSION = "1.2.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: polyrun
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 1.2.0
 platform: ruby
 authors:
 - Andrei Makarov
@@ -167,10 +167,13 @@ files:
 - lib/polyrun.rb
 - lib/polyrun/cli.rb
 - lib/polyrun/cli/ci_shard_run_command.rb
+- lib/polyrun/cli/config_command.rb
 - lib/polyrun/cli/coverage_commands.rb
 - lib/polyrun/cli/coverage_merge_io.rb
 - lib/polyrun/cli/database_commands.rb
+- lib/polyrun/cli/default_run.rb
 - lib/polyrun/cli/env_commands.rb
+- lib/polyrun/cli/help.rb
 - lib/polyrun/cli/helpers.rb
 - lib/polyrun/cli/init_command.rb
 - lib/polyrun/cli/plan_command.rb
@@ -187,6 +190,9 @@ files:
 - lib/polyrun/cli/start_bootstrap.rb
 - lib/polyrun/cli/timing_command.rb
 - lib/polyrun/config.rb
+- lib/polyrun/config/dotted_path.rb
+- lib/polyrun/config/effective.rb
+- lib/polyrun/config/resolver.rb
 - lib/polyrun/coverage/cobertura_zero_lines.rb
 - lib/polyrun/coverage/collector.rb
 - lib/polyrun/coverage/collector_finish.rb