polyrun 2.1.0 → 2.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4ab4d8c8553db3e8e62e83967c9090fc7e788c994d450febb0dc64d39d946f3b
-  data.tar.gz: 3edbc34c324880653c8fd6d7675a31193adfebb0f0a4439d33f74e4ab9d1c327
+  metadata.gz: 756cf8e1b8e2176c4097520752dfdd4b856d03b134a999462641f90a9f217e71
+  data.tar.gz: 284e536d886b4bfc913415b0e3301a31ca98ef3446da1b24163bcc6af485e642
 SHA512:
-  metadata.gz: 1e372f737bf9d8cf76d39979f87dec6acd33e325ef1b5355acdbdb588d9542bc94d0fa0236eecb6632152c0b148560e489a9e26132bede885ddbb73628fa3830
-  data.tar.gz: c61bedba0ea3f6399ffee3d217d719182de6c3e945fbbb14aea9c811f0b75e7e968b7e30a30162fb944635a949629e0102976d0f01e2851411b7694649ac8c5f
+  metadata.gz: 445f64e0e62be50ab6c63026f27ad8f5f093521bbeed4a05b0ce7adc6a13bcb0496f1489d8243b403f859826e599194c3399a761a9210cbbf5d8027f3fdba52e
+  data.tar.gz: 554a292c2c7ac40e3df11d886ca7a71c10b81f1fa144af00c5c1d20b950ff6d999306be1e3fa75a9982450b2d202bc2bee34d5201ab39dbb386b1b73b42f1403

data/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 ## Unreleased
 
+## 2.1.2 (2026-07-05)
+
+- Fix per-example timing JSON when RSpec supplies `absolute_file_path` metadata; fix formatter registration when `install_example_timing!` uses a custom output path.
+
+## 2.1.1 (2026-07-05)
+
+- Fix HTML coverage report `Encoding::CompatibilityError` when source files contain UTF-8; read templates, assets, and source lines as UTF-8 in `formatters_html.rb`.
+
 ## 2.1.0 (2026-07-03)
 
 - Add experimental per-example spec quality (`Polyrun::SpecQuality`): `POLYRUN_SPEC_QUALITY=1`, worker JSONL fragments, `merge-spec-quality`, `report-spec-quality`, and `run-shards --merge-spec-quality`.

data/lib/polyrun/cli/coverage_commands.rb

@@ -92,7 +92,7 @@ module Polyrun
       def merge_coverage_after_shards(output:, format_list:, config_path:)
         files = merge_coverage_fragment_json_files
         if files.empty?
-          Polyrun::Log.warn "polyrun run-shards: --merge-coverage: no coverage/polyrun-fragment-*.json found (enable Polyrun coverage in spec_helper?)"
+          Polyrun::Log.warn "polyrun run-shards: --merge-coverage: no coverage fragments found under coverage (enable coverage collection in your test setup)"
           return 0
         end
 

data/lib/polyrun/cli/failure_commands.rb

@@ -57,7 +57,7 @@ module Polyrun
         pattern = Polyrun::Reporting::FailureMerge.default_fragment_glob
         files = Dir.glob(pattern).sort
         if files.empty?
-          Polyrun::Log.warn "polyrun run-shards: --merge-failures: no #{Polyrun::Reporting::FailureMerge::FRAGMENT_GLOB} under fragment dir (enable Polyrun::RSpec.install_failure_fragments! in spec_helper?)"
+          Polyrun::Log.warn "polyrun run-shards: --merge-failures: no failure fragments found under tmp/polyrun_failures (enable failure fragments in your test setup)"
           return nil
         end
 

data/lib/polyrun/cli/help.rb

@@ -13,21 +13,19 @@ module Polyrun
             -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)
+          Coverage: POLYRUN_COVERAGE=1 (or config/polyrun_coverage.yml + POLYRUN_QUICK_COVERAGE=1); POLYRUN_COVERAGE_DISABLE=1 skips; POLYRUN_COVERAGE_BRANCHES=1 for branch data in fragments
+          Merge profiling (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)
-          Failure fragments (run-shards --merge-failures): POLYRUN_MERGE_FAILURES=1; parent sets POLYRUN_FAILURE_FRAGMENTS=1 in workers; POLYRUN_FAILURE_FRAGMENT_DIR, POLYRUN_MERGED_FAILURES_OUT, POLYRUN_MERGED_FAILURES_FORMAT; after_suite sets POLYRUN_MERGED_FAILURES_PATH when merge ran
-          Parallel RSpec workers: POLYRUN_WORKERS default 5, max 10 (run-shards / parallel-rspec / start); distinct from POLYRUN_SHARD_PROCESSES / ci-shard --shard-processes (local processes per CI matrix job)
-          Per-worker wall timeout: run-shards --worker-timeout SEC or POLYRUN_WORKER_TIMEOUT_SEC (max time since each worker spawn). Parent polls all live workers together. Exit 124; remaining workers stopped.
-          Per-worker idle timeout: --worker-idle-timeout SEC or POLYRUN_WORKER_IDLE_TIMEOUT_SEC counts only after a successful ping timestamp (positive float in POLYRUN_WORKER_PING_FILE); empty or unreadable pings do not satisfy idle enforcement—use wall timeout until the first ping. RSpec/Minitest/Quick installers call Polyrun::WorkerPing.ping! per example/suite. Ping files live under tmp/polyrun/ (gitignored via tmp/); parent unlinks each after its worker exits. Exit 125. Optional outer cap: --worker-timeout (exit 124). Optional periodic pings: POLYRUN_WORKER_PING_THREAD=1 (POLYRUN_WORKER_PING_INTERVAL_SEC); WorkerPing.ensure_interval_ping_thread! (installers invoke it—call yourself if wiring workers without install_worker_ping!).
-          If Polyrun::Log.stderr is null or redirected away, set POLYRUN_ORCHESTRATION_STDERR=1 to also print timeout/SIGINT summary lines to process stderr.
-          Spec quality (opt-in): POLYRUN_SPEC_QUALITY=1; per-example JSONL fragments; POLYRUN_SPEC_QUALITY_SAMPLE=0.0-1.0 (default 1.0); POLYRUN_SPEC_QUALITY_STRICT=1; run-shards --merge-spec-quality sets POLYRUN_SPEC_QUALITY_FRAGMENTS=1 in workers; merge-spec-quality / report-spec-quality
-          Partition timing granularity (default file): POLYRUN_TIMING_GRANULARITY=file|example (experimental per-example; see partition.timing_granularity)
+          Start skips: POLYRUN_SKIP_BUILD_SPEC_PATHS=1, POLYRUN_START_SKIP_PREPARE=1, POLYRUN_START_SKIP_DATABASES=1
+          Paths build skip: POLYRUN_SKIP_PATHS_BUILD=1
+          Slow merge warning (seconds, default 10; 0 disables): POLYRUN_MERGE_SLOW_WARN_SECONDS
+          Failure merge: run-shards --merge-failures (enable failure fragments in test setup); POLYRUN_MERGE_FAILURES=1, POLYRUN_FAILURE_FRAGMENT_DIR, POLYRUN_MERGED_FAILURES_OUT
+          Parallel workers: POLYRUN_WORKERS default 5, max 10 (run-shards / parallel-rspec / start). CI local processes per job: POLYRUN_SHARD_PROCESSES or ci-shard --shard-processes (not POLYRUN_WORKERS)
+          Per-worker wall timeout: --worker-timeout SEC or POLYRUN_WORKER_TIMEOUT_SEC. Exit 124; parent stops remaining workers.
+          Per-worker idle timeout: --worker-idle-timeout SEC or POLYRUN_WORKER_IDLE_TIMEOUT_SEC after a progress ping (POLYRUN_WORKER_PING_FILE). Enable pings in test setup. Exit 125. Optional periodic pings: POLYRUN_WORKER_PING_THREAD=1 (POLYRUN_WORKER_PING_INTERVAL_SEC).
+          Orchestration warnings on process stderr: POLYRUN_ORCHESTRATION_STDERR=1
+          Spec quality (opt-in): POLYRUN_SPEC_QUALITY=1; run-shards --merge-spec-quality; merge-spec-quality / report-spec-quality
+          Partition timing granularity (default file): POLYRUN_TIMING_GRANULARITY=file|example (experimental; see partition.timing_granularity)
           Partition strategies: round_robin (default, sorted), preserve_order_round_robin (paths-file order), lazy_robin (sorted RR + timing diagnostics), cost_binpack (LPT), hrw. partition.timing_file without strategy implies cost_binpack.
 
           commands:
@@ -45,7 +43,7 @@ module Polyrun
             init                 write a starter polyrun.yml or POLYRUN.md from built-in templates (see docs/SETUP_PROFILE.md)
             queue                file-backed batch queue: init (optional --shard/--total etc. as plan, then claim/ack/reclaim/status --json)
             run-queue            init queue and run N workers that claim batches until drained
-            quick                run Polyrun::Quick (describe/it, before/after, let, expect…to, assert_*; optional capybara!)
+            quick                quick test runner (describe/it, before/after, let, expect…to, assert_*; optional capybara!)
             hook run <phase>     run one shell hook from polyrun.yml hooks: (e.g. before_suite); optional --shard/--total
             report-coverage      write all coverage formats from one JSON file
             report-junit         RSpec JSON or Polyrun testcase JSON → JUnit XML (CI)
@@ -53,7 +51,7 @@ module Polyrun
             merge-timing         merge polyrun_timing_*.json shards
             merge-spec-quality   merge polyrun-spec-quality-fragment-*.jsonl shards
             report-spec-quality  spec quality report from merged JSON (zero-hit, hot lines, churn)
-            config               print effective config by dotted path (see Polyrun::Config::Effective; same tree as YAML plus merged prepare.env, resolved partition shard fields, workers)
+            config               print effective config by dotted path (loaded 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)

data/lib/polyrun/cli/run_shards_parallel_wait.rb

@@ -2,6 +2,10 @@
 module Polyrun
   class CLI
     # Wait, wall/idle timeout, and +after_shard+ hooks for parallel workers (+run-shards+ / +ci-shard-*+).
+    #
+    # Per-worker wait states: running → normal_exit | wall_timeout (124) | idle_timeout (125).
+    # When wall or idle caps are set, the multiplex loop polls every live PID each tick so timeouts
+    # apply fairly across shards (not only the worker currently in Process.wait).
     module RunShardsParallelWait
       WORKER_TIMEOUT_EXIT_STATUS = 124
       WORKER_IDLE_TIMEOUT_EXIT_STATUS = 125
@@ -215,7 +219,7 @@ module Polyrun
         ping_suffix = (loc && !loc.to_s.strip.empty?) ? "; last ping #{loc.to_s.strip}" : ""
         Polyrun::Log.orchestration_warn "polyrun run-shards: WORKER IDLE TIMEOUT after #{idle_sec}s since last per-example progress ping — shard #{h[:shard]} pid #{h[:pid]}#{ping_suffix}."
         Polyrun::Log.warn "polyrun run-shards: idle shard file sample: #{sample}#{suffix}"
-        Polyrun::Log.warn "polyrun run-shards: use Polyrun::RSpec.install_worker_ping! / Polyrun::Minitest.install_worker_ping! (Polyrun Quick calls ping! each example); exit #{WORKER_IDLE_TIMEOUT_EXIT_STATUS}."
+        Polyrun::Log.warn "polyrun run-shards: enable per-example worker progress pings in your test setup so idle timeouts reflect real work; exit #{WORKER_IDLE_TIMEOUT_EXIT_STATUS}."
       end
 
       def run_shards_wait_or_force_stop_status(pid)

data/lib/polyrun/cli/run_shards_plan_options.rb

@@ -48,7 +48,7 @@ module Polyrun
         opts.banner = "usage: polyrun run-shards [--workers N] [--worker-timeout SEC] [--worker-idle-timeout SEC] [--strategy NAME] [--paths-file P] [--timing P] [--timing-granularity VAL] [--constraints P] [--seed S] [--merge-coverage] [--merge-output P] [--merge-format LIST] [--merge-failures] [--merge-failures-output P] [--merge-failures-format jsonl|json] [--merge-spec-quality] [--merge-spec-quality-output P] [--no-report-spec-quality] [--] <command> [args...]"
         opts.on("--workers N", Integer) { |v| st[:workers] = v }
         opts.on("--worker-timeout SEC", Float, "Max seconds per worker since spawn (also POLYRUN_WORKER_TIMEOUT_SEC); kills stuck workers (exit 124)") { |v| st[:worker_timeout_sec] = v }
-        opts.on("--worker-idle-timeout SEC", Float, "Max seconds since last valid WorkerPing timestamp in POLYRUN_WORKER_PING_FILE (needs prior ping); RSpec/Minitest: install_worker_ping!; Quick: automatic; exit 125") { |v| st[:worker_idle_timeout_sec] = v }
+        opts.on("--worker-idle-timeout SEC", Float, "Max seconds since last worker progress ping (POLYRUN_WORKER_PING_FILE); enable pings in test setup; exit 125") { |v| st[:worker_idle_timeout_sec] = v }
         opts.on("--strategy NAME", String) do |v|
           st[:strategy] = v
           st[:strategy_explicit] = true
@@ -61,10 +61,10 @@ module Polyrun
         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 }
-        opts.on("--merge-failures", "After all workers exit, merge tmp/polyrun_failures/polyrun-failure-fragment-*.jsonl (use Polyrun::RSpec.install_failure_fragments!)") { st[:merge_failures] = true }
+        opts.on("--merge-failures", "After all workers exit, merge failure fragments from tmp/polyrun_failures (requires failure fragments in test setup)") { st[:merge_failures] = true }
         opts.on("--merge-failures-output PATH", String) { |v| st[:merge_failures_output] = v }
         opts.on("--merge-failures-format VAL", "jsonl (default) or json") { |v| st[:merge_failures_format] = v }
-        opts.on("--merge-spec-quality", "After workers exit, merge coverage/polyrun-spec-quality-fragment-*.jsonl (POLYRUN_SPEC_QUALITY in workers)") { st[:merge_spec_quality] = true }
+        opts.on("--merge-spec-quality", "After workers exit, merge spec-quality fragments from coverage (enable spec-quality collection in test setup)") { st[:merge_spec_quality] = true }
         opts.on("--merge-spec-quality-output PATH", String) { |v| st[:merge_spec_quality_output] = v }
         opts.on("--no-report-spec-quality", "Skip printing spec-quality report after merge") { st[:report_spec_quality] = false }
       end

data/lib/polyrun/cli/run_shards_run.rb

@@ -162,7 +162,7 @@ module Polyrun
           Polyrun::Log.warn "polyrun run-shards: shard #{s} re-run (same spec list, no interleave): #{rerun}"
         end
         unless merge_failures
-          Polyrun::Log.warn "polyrun run-shards: one merged failure report — use run-shards --merge-failures with Polyrun::RSpec.install_failure_fragments!; POLYRUN_MERGED_FAILURES_PATH is set on after_suite when merge runs."
+          Polyrun::Log.warn "polyrun run-shards: for one combined failure report, add --merge-failures (requires failure fragments enabled in your test setup)"
         end
       end
     end

data/lib/polyrun/cli/spec_quality_commands.rb

@@ -96,7 +96,7 @@ module Polyrun
       def merge_spec_quality_after_shards(ctx)
         files = merge_spec_quality_fragment_files
         if files.empty?
-          Polyrun::Log.warn "polyrun run-shards: --merge-spec-quality: no coverage/polyrun-spec-quality-fragment-*.jsonl found (enable POLYRUN_SPEC_QUALITY in spec_helper?)"
+          Polyrun::Log.warn "polyrun run-shards: --merge-spec-quality: no spec-quality fragments found under coverage (enable spec-quality collection in your test setup)"
           return nil
         end
 

data/lib/polyrun/coverage/merge/formatters_html.rb

@@ -23,14 +23,14 @@ module Polyrun
         )
         file_list_html = render_html_partial("file_list", file_rows_html: files.map { |file| html_file_list_row(file) }.join("\n"))
         file_sections_html = files.map { |file| render_html_partial("file_section", file: file) }.join("\n")
-        ERB.new(File.read(html_template_path), trim_mode: "-").result_with_hash(
+        ERB.new(File.read(html_template_path, encoding: Encoding::UTF_8), trim_mode: "-").result_with_hash(
           title: CGI.escapeHTML(title.to_s),
           generated_label: html_generated_label(generated_at),
           overview_html: overview_html,
           file_list_html: file_list_html,
           file_sections_html: file_sections_html,
-          stylesheet: File.read(html_stylesheet_path),
-          javascript: File.read(html_javascript_path)
+          stylesheet: File.read(html_stylesheet_path, encoding: Encoding::UTF_8),
+          javascript: File.read(html_javascript_path, encoding: Encoding::UTF_8)
         )
       end
       # rubocop:enable Metrics/AbcSize
@@ -56,7 +56,7 @@ module Polyrun
       end
 
       def render_html_partial(name, locals = {})
-        ERB.new(File.read(html_partial_path(name)), trim_mode: "-").result_with_hash(locals)
+        ERB.new(File.read(html_partial_path(name), encoding: Encoding::UTF_8), trim_mode: "-").result_with_hash(locals)
       end
 
       def html_file_payload(path, file, root)
@@ -152,7 +152,7 @@ module Polyrun
       def html_source_lines(path, fallback_length)
         return Array.new(fallback_length, "") unless File.file?(path.to_s)
 
-        File.readlines(path.to_s, chomp: true)
+        File.readlines(path.to_s, chomp: true, encoding: Encoding::UTF_8)
       rescue Errno::ENOENT, Errno::EACCES, ArgumentError
         Array.new(fallback_length, "")
       end

data/lib/polyrun/queue/file_store.rb

@@ -6,6 +6,13 @@ require "time"
 module Polyrun
   module Queue
     # File-backed queue (spec_queue.md): +queue.json+, +pending/*.json+ chunks, +done.jsonl+, +leases.json+ (OS flock).
+    #
+    # Path lifecycle (lease transitions):
+    #   init!           → paths in pending chunks only
+    #   claim!          → pending −batch → active lease in leases.json
+    #   ack!            → lease removed; paths appended to done.jsonl
+    #   reclaim!        → stale or matching lease → paths returned to pending
+    #   reclaim_lease!  → one lease by id → paths returned to pending
     class FileStore
       CHUNK_SIZE = 500
 

data/lib/polyrun/rspec.rb

@@ -21,6 +21,8 @@ module Polyrun
         if output_path
           op = output_path
           Class.new(Polyrun::Timing::RSpecExampleFormatter) do
+            ::RSpec::Core::Formatters.register self, :example_finished, :close
+
             define_method(:timing_output_path) { op }
           end
         else

data/lib/polyrun/timing/rspec_example_formatter.rb

@@ -1,6 +1,6 @@
 require "json"
 
-require "rspec/core/formatters/base_formatter"
+require "rspec/core/formatters"
 
 module Polyrun
   module Timing
@@ -13,23 +13,23 @@ module Polyrun
     # Or {Polyrun::RSpec.install_example_timing!} (+output_path:+ avoids touching +ENV+).
     #
     # Default output path: +ENV["POLYRUN_EXAMPLE_TIMING_OUT"]+ if set, else +polyrun_timing_examples.json+.
-    class RSpecExampleFormatter < RSpec::Core::Formatters::BaseFormatter
-      RSpec::Core::Formatters.register self, :example_finished, :close
+    class RSpecExampleFormatter
+      ::RSpec::Core::Formatters.register self, :example_finished, :close
 
       def initialize(output)
-        super
+        @output = output
         @times = {}
       end
 
       def example_finished(notification)
         ex = notification.example
-        result = ex.execution_result
-        return if result.pending?
+        return if ex.pending?
 
+        result = ex.execution_result
         t = result.run_time
         return unless t
 
-        path = ex.metadata[:absolute_path]
+        path = example_absolute_path(ex)
         return unless path
 
         line = ex.metadata[:line_number]
@@ -48,6 +48,13 @@ module Polyrun
       def timing_output_path
         ENV["POLYRUN_EXAMPLE_TIMING_OUT"] || "polyrun_timing_examples.json"
       end
+
+      private
+
+      def example_absolute_path(example)
+        metadata = example.metadata
+        metadata[:absolute_file_path] || metadata[:file_path] || metadata[:absolute_path]
+      end
     end
   end
 end

data/lib/polyrun/version.rb

@@ -1,3 +1,3 @@
 module Polyrun
-  VERSION = "2.1.0"
+  VERSION = "2.1.2"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: polyrun
 version: !ruby/object:Gem::Version
-  version: 2.1.0
+  version: 2.1.2
 platform: ruby
 authors:
 - Andrei Makarov