polyrun 1.0.0 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ca0c4afee7136f1cdf3ffe319d55c08457323119102a0a4d01478b02df91ce31
-  data.tar.gz: d468805765ee230bed530fdce182f189c0521e3dff7516be5c75bc620c362fc8
+  metadata.gz: 5dd8b178e07e0cf6648284d59d5b8f58a5feceeb2c7570edfd381aafaed207cb
+  data.tar.gz: cd2846dc77b56bccf0ac411fcc4f6a2a7aaf2e106609172e84299c2a1d253f64
 SHA512:
-  metadata.gz: 98e04c5388e51da737bb73407497830d82bf61daabdfd77e9024fd2d973663dfed934c87691c6f2e864d7642e457a1eaaff27e3cf3f79bfa102a92ec9a0034aa
-  data.tar.gz: b6c407039df97914ed8e07a04bdb0dc4c8e044d9b0ffd3802e44e600a6c4002fe22b8673266263c5981bb4bde90246c992defb589eb3b785952b0c56f67c263e
+  metadata.gz: c9a71f317d28ce3dcdf25d9c8e08221e71eadb2cf044217170ca0ba08cdc22cb702e6adaf02383d4e6089fa2fdddc94198cc420f031f53186715b67c14c92567
+  data.tar.gz: 81469ea975e78befbf6c66e3482e5c6006c11bb8b1806a079545a00ac057f250d49323aeab6685e8eaec22ff65e5aa72fb28aaca688365048483650d3c78de00

data/CHANGELOG.md

@@ -0,0 +1,35 @@
+# 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).
+- Add experimental per-example partition timing: `partition.timing_granularity` / `--timing-granularity` (`file` default, `example` for `path:line` items), `POLYRUN_TIMING_GRANULARITY`, merged timing JSON with `absolute_path:line` keys, `TimingKeys.load_costs_json_file`, constraints matching pins/globs on the file part of locators, queue init support, and optional `Polyrun::Timing::RSpecExampleFormatter` plus `Polyrun::RSpec.install_example_timing!`.
+- Add `Polyrun::ProcessStdio.inherit_stdio_spawn_wait` and `spawn_wait` for subprocesses with inherited stdio (or temp-file capture when `silent: true`) to avoid Open3 pipe-thread noise on interrupt; used by prepare (shell / custom assets), `Prepare::Assets.precompile!`, and `Provision.prepare_template!` (`bin/rails db:prepare`). On failure, `db:prepare` / `assets:precompile` embed captured stdout/stderr in `Polyrun::Error` (truncated when huge).
+- Refactor `polyrun plan` around `plan_command_compute_manifest` and `plan_command_build_manifest`; `cmd_plan` output stays aligned with `plan_command_compute_manifest` (tests guard drift).
+- `TimingKeys.load_costs_json_file` accepts optional `root:` for key normalization; warns when two JSON keys normalize to the same entry with different seconds; `TimingKeys.canonical_file_path` / `normalize_locator` resolve directory symlinks so `/var/…` and `/private/var/…` (macOS) map to one key.
+- `Polyrun::RSpec.install_example_timing!(output_path:)` no longer sets `ENV` when an explicit path is passed; formatter uses `timing_output_path` (override or `ENV` / default filename).
+- Fix noisy `IOError` / broken-pipe behavior when interrupting long-running prepare / Rails subprocesses that previously used `Open3.capture3`.
+
+## 1.0.0 (2026-04-14)
+
+- Initial stable release of Polyrun: parallel tests, SimpleCov-compatible coverage formatters, fixtures/snapshots, assets and DB provisioning with zero runtime gem dependencies.
+- Add `polyrun` CLI with `plan`, `run-shards`, partition/load balancing, coverage merge and reporting, database helpers, queue helpers, and the Quick runner.
+- Add coverage Rake tasks and YAML configuration for merged / Cobertura-style output.
+- Add database command flows using `db:prepare` (replacing earlier `db:migrate`-only paths) for provisioning-style runs.
+- Implement graceful shutdown for worker processes in `run_shards` when the parent is interrupted.
+- Expand Quick runner defaults and parallel shard database creation.
+- Add examples tree, specs for merge and queue behavior, and docs for cwd-relative configuration.
+- Add RSpec suite, RuboCop (including a FileLength cop), YAML templates, and a `bin/release` script.
+- Add RBS signatures under `sig/` and validate them in CI; expand documentation and specs.

data/README.md

@@ -8,7 +8,7 @@ Running tests in parallel across processes still requires a single merged covera
 
 Polyrun provides:
 
-- Orchestration: `plan`, `run-shards`, and `parallel-rspec` (run-shards plus merge-coverage), with an optional on-disk queue and constraints for file lists and load balancing.
+- Orchestration: `plan`, `run-shards`, and `parallel-rspec` (run-shards plus merge-coverage), with an optional on-disk queue and constraints for file lists and load balancing. For **GitHub Actions-style matrix sharding** (one job per global shard), use `ci-shard-run -- …` (any test runner) or `ci-shard-rspec`—not `run-shards` / `parallel-rspec`, which fan out N workers on one machine.
 - Coverage: merge SimpleCov-compatible JSON fragments; emit JSON, LCOV, Cobertura, or console summaries (you can drop separate SimpleCov merge plugins for this path).
 - CI reporting: JUnit XML from RSpec JSON; slow-file reports from merged timing JSON.
 - Parallel hygiene: asset digest markers, SQL snapshots, YAML fixture batches, and DB URL or shard helpers aligned with `POLYRUN_SHARD_*`.
@@ -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`.
@@ -32,6 +32,8 @@ If the current directory already has `polyrun.yml` or `config/polyrun.yml`, you
 ```bash
 bin/polyrun version
 bin/polyrun build-paths   # write spec/spec_paths.txt from partition.paths_build (uses polyrun.yml in cwd)
+bin/polyrun ci-shard-run -- bundle exec rspec   # CI matrix: shard plan + append paths to the command after --
+bin/polyrun ci-shard-rspec   # same as ci-shard-run -- bundle exec rspec
 bin/polyrun parallel-rspec --workers 5   # run-shards + merge-coverage (default: bundle exec rspec)
 bin/polyrun run-shards --workers 5 --merge-coverage -- bundle exec rspec
 bin/polyrun merge-coverage -i cov1.json -i cov2.json -o merged.json --format json,lcov,cobertura,console
@@ -41,6 +43,12 @@ bin/polyrun init --profile gem -o polyrun.yml   # starter YAML; see docs/SETUP_P
 bin/polyrun quick   # Polyrun::Quick examples under spec/polyrun_quick/ or test/polyrun_quick/
 ```
 
+### Matrix shards and timing
+
+- `ci-shard-run` — Pass the command as separate words after `--` (e.g. `ci-shard-run -- bundle exec rspec`). One combined string with spaces is split via `Shellwords`, not a full shell; shell-only quoting does not apply.
+- Timing JSON — Run `plan`, `queue init`, and `merge-timing` from the same repository root (cwd) you use when producing `polyrun_timing.json` so path keys normalize consistently. `Polyrun::Partition::Plan.load_timing_costs` and `TimingKeys.load_costs_json_file` accept `root:` to align keys to a fixed directory.
+- Per-example timing (`--timing-granularity example`) — Experimental. Cost maps and plan items scale with example count, not file count; expect larger memory use and slower planning than file mode on big suites.
+
 ### Adopting Polyrun (setup profile and scaffolds)
 
 - [docs/SETUP_PROFILE.md](docs/SETUP_PROFILE.md) — Checklist for project type (gem, Rails, Appraisal), parallelism target (one CI job with N workers, matrix shards, or a single non-matrix runner), database layout, prepare, spec order, coverage, and CI model A (single runner with `parallel-rspec`) versus model B (matrix plus a merge-coverage job). Treat `polyrun.yml` as the contract; bin scripts and `database.yml` are adapters.
@@ -131,7 +139,19 @@ See [`examples/README.md`](examples/README.md) for Rails apps (Capybara, Playwri
 
 You can replace SimpleCov and simplecov plugins, parallel_tests, and rspec_junit_formatter with Polyrun for those roles. Use `merge-timing`, `report-timing`, and `Data::FactoryCounts` (optionally with `Data::FactoryInstrumentation`) for slow-file and factory metrics. YAML fixture batches and bulk inserts can use `Data::Fixtures` and `ParallelProvisioning` for shard-aware seeding; wire your own `truncate` and `load_seed` in hooks.
 
----
+## License
+
+Released under the [MIT License](LICENSE). Copyright (c) 2026 Andrei Makarov.
+
+## Contributing
+
+Bug reports and pull requests are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, tests, RuboCop, RBS, optional Trunk, and PR conventions. Community participation follows [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md).
+
+## Security
+
+Do not open public issues for security vulnerabilities. See [SECURITY.md](SECURITY.md) for how to report them.
+
+## Sponsors
 
 Sponsored by [Kisko Labs](https://www.kiskolabs.com).
 

data/docs/SETUP_PROFILE.md

@@ -81,7 +81,7 @@ Model A — one job, N worker processes
 Model B — matrix of jobs (one shard per job)
 
 - Each job sets `POLYRUN_SHARD_INDEX` / `POLYRUN_SHARD_TOTAL` (and DB URLs per shard if needed).
-- Run `polyrun build-paths`, `polyrun plan`, then `bundle exec rspec` (or `bin/rspec_ci_shard`) for that shard only.
+- Run `polyrun ci-shard-run -- bundle exec rspec` (or `ci-shard-rspec`), or `ci-shard-run -- bundle exec polyrun quick` / other runners; or the same steps manually (`bin/rspec_ci_shard` wrappers).
 - Upload `coverage/polyrun-fragment-*.json` (or named per shard).
 - A final `merge-coverage` job downloads artifacts and merges.
 

data/lib/polyrun/cli/ci_shard_run_command.rb

@@ -0,0 +1,65 @@
+require "shellwords"
+
+module Polyrun
+  class CLI
+    # One CI matrix job = one global shard (POLYRUN_SHARD_INDEX / POLYRUN_SHARD_TOTAL), not +run-shards+
+    # workers on a single host. Runs +build-paths+, +plan+ for that shard, then +exec+ of a user command
+    # with that shard's paths appended (same argv pattern as +run-shards+ after +--+).
+    #
+    # After +--+, prefer **multiple argv tokens** (+bundle+, +exec+, +rspec+, …). A single token that
+    # contains spaces is split with +Shellwords+ (not a full shell); exotic quoting differs from +sh -c+.
+    module CiShardRunCommand
+      private
+
+      # @return [Array(Array<String>, Integer)] [paths, 0] on success, or [nil, exit_code] on failure
+      def ci_shard_planned_paths!(plan_argv, config_path, command_label:)
+        manifest, code = plan_command_compute_manifest(plan_argv, config_path)
+        return [nil, code] if code != 0
+
+        paths = manifest["paths"] || []
+        if paths.empty?
+          Polyrun::Log.warn "polyrun #{command_label}: no paths for this shard (check shard/total and paths list)"
+          return [nil, 2]
+        end
+
+        [paths, 0]
+      end
+
+      # Runner-agnostic matrix shard: +polyrun ci-shard-run [plan options] -- <command> [args...]+
+      # Paths for this shard are appended after the command (like +run-shards+).
+      def cmd_ci_shard_run(argv, config_path)
+        sep = argv.index("--")
+        unless sep
+          Polyrun::Log.warn "polyrun ci-shard-run: need -- before the command (e.g. ci-shard-run -- bundle exec rspec)"
+          return 2
+        end
+
+        plan_argv = argv[0...sep]
+        cmd = argv[(sep + 1)..].map(&:to_s)
+        if cmd.empty?
+          Polyrun::Log.warn "polyrun ci-shard-run: empty command after --"
+          return 2
+        end
+        cmd = Shellwords.split(cmd.first) if cmd.size == 1 && cmd.first.include?(" ")
+
+        paths, code = ci_shard_planned_paths!(plan_argv, config_path, command_label: "ci-shard-run")
+        return code if code != 0
+
+        exec(*cmd, *paths)
+      end
+
+      # Same as +ci-shard-run -- bundle exec rspec+ with an optional second segment for RSpec-only flags:
+      # +polyrun ci-shard-rspec [plan options] [-- [rspec args]]+
+      def cmd_ci_shard_rspec(argv, config_path)
+        sep = argv.index("--")
+        plan_argv = sep ? argv[0...sep] : argv
+        rspec_argv = sep ? argv[(sep + 1)..] : []
+
+        paths, code = ci_shard_planned_paths!(plan_argv, config_path, command_label: "ci-shard-rspec")
+        return code if code != 0
+
+        exec("bundle", "exec", "rspec", *rspec_argv, *paths)
+      end
+    end
+  end
+end

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

@@ -1,44 +1,22 @@
 require "yaml"
 
+require_relative "../partition/timing_keys"
+
 module Polyrun
   class CLI
     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)
@@ -95,9 +73,15 @@ module Polyrun
 
       # +default_weight+ should be precomputed when sorting many paths (e.g. +queue init+), matching
       # {Partition::Plan#default_weight} semantics: mean of known timing costs for missing paths.
-      def queue_weight_for(path, costs, default_weight = nil)
-        abs = File.expand_path(path.to_s, Dir.pwd)
-        return costs[abs] if costs.key?(abs)
+      def queue_weight_for(path, costs, default_weight = nil, granularity: :file)
+        g = Polyrun::Partition::TimingKeys.normalize_granularity(granularity)
+        key =
+          if g == :example
+            Polyrun::Partition::TimingKeys.normalize_locator(path.to_s, Dir.pwd, :example)
+          else
+            File.expand_path(path.to_s, Dir.pwd)
+          end
+        return costs[key] if costs.key?(key)
 
         unless default_weight.nil?
           return default_weight
@@ -108,6 +92,11 @@ module Polyrun
 
         vals.sum / vals.size.to_f
       end
+
+      # CLI + polyrun.yml + POLYRUN_TIMING_GRANULARITY; default +:file+.
+      def resolve_partition_timing_granularity(pc, cli_val)
+        Polyrun::Config::Resolver.resolve_partition_timing_granularity(pc, cli_val)
+      end
     end
   end
 end

data/lib/polyrun/cli/plan_command.rb

@@ -7,6 +7,15 @@ module Polyrun
       private
 
       def cmd_plan(argv, config_path)
+        manifest, code = plan_command_compute_manifest(argv, config_path)
+        return code if code != 0
+
+        Polyrun::Log.puts JSON.generate(manifest)
+        0
+      end
+
+      # @return [Array(Hash, Integer)] manifest hash and exit code (+0+ on success, non-zero on failure)
+      def plan_command_compute_manifest(argv, config_path)
         cfg = Polyrun::Config.load(path: config_path || ENV["POLYRUN_CONFIG"])
         pc = cfg.partition
         ctx = plan_command_initial_context(pc)
@@ -14,30 +23,44 @@ module Polyrun
 
         paths_file = ctx[:paths_file] || (pc["paths_file"] || pc[:paths_file])
         code = Polyrun::Partition::PathsBuild.apply!(partition: pc, cwd: Dir.pwd)
-        return code if code != 0
+        return [nil, code] if code != 0
 
+        plan_command_manifest_from_paths(cfg, pc, argv, ctx, paths_file)
+      end
+
+      def plan_command_manifest_from_paths(cfg, pc, argv, ctx, paths_file)
         timing_path = plan_resolve_timing_path(pc, ctx[:timing_path], ctx[:strategy])
+        ctx[:timing_granularity] = resolve_partition_timing_granularity(pc, ctx[:timing_granularity])
         Polyrun::Log.warn "polyrun plan: using #{cfg.path}" if @verbose && cfg.path
 
-        items = plan_plan_items(paths_file, argv)
-        return 2 if items.nil?
-
-        loaded = plan_load_costs_and_strategy(timing_path, ctx[:strategy])
-        return 2 if loaded.nil?
-
-        costs, strategy = loaded
+        bundle = plan_command_items_costs_strategy(paths_file, argv, timing_path, ctx)
+        return [nil, 2] if bundle.nil?
 
+        items, costs, strategy = bundle
         constraints = load_partition_constraints(pc, ctx[:constraints_path])
 
-        plan_command_emit_manifest(
+        manifest = plan_command_build_manifest(
           items: items,
           total: ctx[:total],
           strategy: strategy,
           seed: ctx[:seed],
           costs: costs,
           constraints: constraints,
-          shard: ctx[:shard]
+          shard: ctx[:shard],
+          timing_granularity: ctx[:timing_granularity]
         )
+        [manifest, 0]
+      end
+
+      def plan_command_items_costs_strategy(paths_file, argv, timing_path, ctx)
+        items = plan_plan_items(paths_file, argv)
+        return nil if items.nil?
+
+        loaded = plan_load_costs_and_strategy(timing_path, ctx[:strategy], ctx[:timing_granularity])
+        return nil if loaded.nil?
+
+        costs, strategy = loaded
+        [items, costs, strategy]
       end
 
       def plan_command_initial_context(pc)
@@ -48,7 +71,8 @@ module Polyrun
           seed: pc["seed"] || pc[:seed],
           paths_file: nil,
           timing_path: nil,
-          constraints_path: nil
+          constraints_path: nil,
+          timing_granularity: nil
         }
       end
 
@@ -64,10 +88,13 @@ module Polyrun
           opts.on("--timing PATH", "path => seconds JSON; implies cost_binpack unless strategy is cost-based or hrw") do |v|
             ctx[:timing_path] = v
           end
+          opts.on("--timing-granularity VAL", "file (default) or example (experimental: path:line items)") do |v|
+            ctx[:timing_granularity] = v
+          end
         end.parse!(argv)
       end
 
-      def plan_command_emit_manifest(items:, total:, strategy:, seed:, costs:, constraints:, shard:)
+      def plan_command_build_manifest(items:, total:, strategy:, seed:, costs:, constraints:, shard:, timing_granularity: :file)
         plan = Polyrun::Debug.time("Partition::Plan.new (plan command)") do
           Polyrun::Partition::Plan.new(
             items: items,
@@ -76,7 +103,8 @@ module Polyrun
             seed: seed,
             costs: costs,
             constraints: constraints,
-            root: Dir.pwd
+            root: Dir.pwd,
+            timing_granularity: timing_granularity
           )
         end
         Polyrun::Debug.log_kv(
@@ -86,8 +114,7 @@ module Polyrun
           strategy: strategy,
           path_count: items.size
         )
-        Polyrun::Log.puts JSON.generate(plan.manifest(shard))
-        0
+        plan.manifest(shard)
       end
 
       def plan_resolve_timing_path(pc, timing_path, strategy)
@@ -110,9 +137,12 @@ module Polyrun
         end
       end
 
-      def plan_load_costs_and_strategy(timing_path, strategy)
+      def plan_load_costs_and_strategy(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 plan: timing file missing or has no entries: #{timing_path}"
             return nil

data/lib/polyrun/cli/prepare_command.rb

@@ -1,5 +1,4 @@
 require "json"
-require "open3"
 require "optparse"
 
 require_relative "prepare_recipe"
@@ -20,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)