polyrun 1.4.0 → 1.4.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 04bfc3ed1a2c01072864dd179decce4d13c68221bba4da0964f4ea600401b57c
-  data.tar.gz: df02fc828fb8ac8c9cf3792ae08420ee87d328a89d79a7eeec26c9e239506ee4
+  metadata.gz: f37969f7a73313a98aa0fd343ae1ed871a32b6dc504da56dd5cb51f42ef2969a
+  data.tar.gz: 3e17734a4419ea15b243ad01261701106d99e3470e4408d2b545deb5876ddcf3
 SHA512:
-  metadata.gz: 378921ebc46b80562c5ae4bb529a3035eed7366cbfbcffd9a5c4bcb1d18f1c1fe6b737dfcc580c9b7e3fb1ce4360ac9ad04c7a7edbc50e4763a2e5430a61c873
-  data.tar.gz: 552545582ab8c34e1411834d5f5ef6d1b6f1d022ead68746059b709cd04d733c6d778b13621c003ec2f4525367bdb5e849577d109e2e04835fcf9b12407bf2ef
+  metadata.gz: 68b10554a23d62042db0d6d5307933ffdbb0fb58cc2452b78e1fca2e1a9b42095bc25e7e98b6b104f30a8be6cb0c4aad09212a57b1f4bbdbd2e2efad3501e3fc
+  data.tar.gz: 70594cb4f7cd5fb32be05aa0da60058e0fc9b50c9ca3ae4223e88a39293a5199e078eda52a2cb461f6782011aa22f05e3ca5efdc7b52cacc184f67a7326c13db

data/CHANGELOG.md

@@ -1,5 +1,22 @@
 # CHANGELOG
 
+## Unreleased
+
+## 1.4.2 (2026-04-24)
+
+- Add richer HTML coverage reports: summary cards, group coverage, sortable file tables, project-relative paths, and per-file source detail.
+- Refactor HTML coverage rendering into stdlib `ERB` templates with `_*.html.erb` partials and isolated `report.css` / `report.js` assets; inline assets into final standalone report.
+- Fix `track_files` coverage scope in `Collector.finish`: keep only files matched by tracked globs, drop unrelated loaded runtime files, and add unloaded tracked files only for non-sharded runs.
+- Add coverage specs for divergent `track_under` / `track_files` configs in serial and sharded finish paths; add `TrackFiles.keep_tracked_files`.
+
+## 1.4.1 (2026-04-16)
+
+- Add `polyrun merge-failures` and `run-shards --merge-failures` / `--merge-failures-output` / `--merge-failures-format`; merge per-worker JSONL under `tmp/polyrun_failures/polyrun-failure-fragment-*.jsonl` (or RSpec JSON via `-i`). Run merge after all workers exit, including when a shard failed (`--merge-coverage` still runs only after all shards succeed).
+- Add `Polyrun::Reporting::FailureMerge`, `Polyrun::RSpec.install_failure_fragments!`, and `Polyrun::Reporting::RspecFailureFragmentFormatter`; parent sets `POLYRUN_FAILURE_FRAGMENTS=1` on workers when merge-failures is enabled.
+- Add optional `reporting:` in `polyrun.yml` and `Polyrun::Config#reporting` for merge-failures toggles and paths; honor `POLYRUN_MERGE_FAILURES`, `POLYRUN_MERGED_FAILURES_OUT`, `POLYRUN_MERGED_FAILURES_FORMAT`; set `POLYRUN_MERGED_FAILURES_PATH` for `after_suite` when merge wrote a file.
+- On bad JSONL or non-RSpec JSON, raise `Polyrun::Error` with path and line where applicable; `merge-failures` exits 1 without a full stack trace; a failed merge after successful workers forces `run-shards` exit 1.
+- Fix `run_shards_plan_ready_log` to take `cfg` so debug logging for merge-failures does not raise `NameError`.
+
 ## 1.4.0 (2026-04-16)
 
 - Add `hooks:` in `polyrun.yml` — shell commands for `before_suite` / `after_suite`, `before_shard` / `after_shard`, `before_worker` / `after_worker` (RSpec-style YAML keys `before(:suite)`, `before(:all)`, `before(:each)` accepted). Wire hooks into `run-shards`, `parallel-rspec`, and `ci-shard-*`.

data/lib/polyrun/cli/failure_commands.rb

@@ -0,0 +1,92 @@
+require "json"
+require "fileutils"
+require "optparse"
+
+require_relative "../reporting/failure_merge"
+
+module Polyrun
+  class CLI
+    module FailureCommands
+      private
+
+      def cmd_merge_failures(argv, _config_path)
+        inputs, output, format = merge_failures_parse_argv(argv)
+        if inputs.empty?
+          Polyrun::Log.warn "merge-failures: need at least one existing -i FILE (after glob expansion)"
+          return 2
+        end
+        Polyrun::Log.warn "merge-failures: merging #{inputs.size} fragment(s)" if @verbose
+        n = merge_failures_merge_files_or_warn!(inputs, output: output, format: format)
+        return 1 if n.nil?
+
+        Polyrun::Log.puts File.expand_path(output)
+        Polyrun::Log.warn "merge-failures: #{n} failure row(s)" if @verbose
+        0
+      end
+
+      def merge_failures_merge_files_or_warn!(inputs, output:, format:)
+        Polyrun::Reporting::FailureMerge.merge_files!(inputs, output: output, format: format)
+      rescue Polyrun::Error => e
+        Polyrun::Log.warn e.message.to_s
+        nil
+      end
+
+      def merge_failures_parse_argv(argv)
+        inputs = []
+        output = File.join("tmp", "polyrun_failures", "merged.jsonl")
+        format = "jsonl"
+        OptionParser.new do |opts|
+          opts.banner = "usage: polyrun merge-failures -i FILE [-i FILE] [-o PATH] [--format jsonl|json]"
+          opts.on("-i", "--input FILE", "JSONL fragment or RSpec JSON (repeatable; globs ok)") do |f|
+            expand_merge_input_pattern(f).each { |x| inputs << x }
+          end
+          opts.on("-o", "--output PATH", String) { |v| output = v }
+          opts.on("--format VAL", "jsonl (default) or json") { |v| format = v }
+        end.parse!(argv)
+        inputs.uniq!
+        inputs.select! { |p| File.file?(p) }
+        [inputs, output, format]
+      end
+
+      # After run-shards workers exit: merge polyrun failure fragments when requested.
+      # Runs even when shards failed (unlike --merge-coverage).
+      # @return [String, nil] absolute path to merged file, or nil when skipped / nothing written
+      def merge_failures_after_shards(ctx)
+        return nil unless ctx[:merge_failures]
+
+        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?)"
+          return nil
+        end
+
+        fmt = merge_failures_resolved_format(ctx)
+        out = merge_failures_resolved_output_path(ctx, fmt)
+        Polyrun::Log.warn "polyrun run-shards: merging #{files.size} failure fragment(s) → #{out} (#{fmt})"
+        Polyrun::Debug.log_kv(merge_failures: "start", output: out, inputs: files, format: fmt)
+        n = Polyrun::Reporting::FailureMerge.merge_files!(files, output: out, format: fmt)
+        Polyrun::Debug.log_kv(merge_failures: "done", rows: n, output: File.expand_path(out))
+        File.expand_path(out)
+      end
+
+      def merge_failures_resolved_format(ctx)
+        f = ctx[:merge_failures_format].to_s.strip.downcase
+        return "jsonl" if f.empty?
+        return "jsonl" if f == "jsonl"
+        return "json" if f == "json"
+
+        Polyrun::Log.warn "polyrun run-shards: unknown merge_failures_format=#{ctx[:merge_failures_format].inspect}; using jsonl"
+        "jsonl"
+      end
+
+      def merge_failures_resolved_output_path(ctx, fmt)
+        raw = ctx[:merge_failures_output]
+        return File.expand_path(raw) if raw && !raw.to_s.strip.empty?
+
+        ext = (fmt == "json") ? "json" : "jsonl"
+        File.expand_path(File.join("tmp", "polyrun_failures", "merged.#{ext}"))
+      end
+    end
+  end
+end

data/lib/polyrun/cli/help.rb

@@ -21,6 +21,7 @@ module Polyrun
           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)
           Partition timing granularity (default file): POLYRUN_TIMING_GRANULARITY=file|example (experimental per-example; see partition.timing_granularity)
 
@@ -29,7 +30,8 @@ module Polyrun
             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
+            merge-failures       merge per-shard failure JSONL fragments or RSpec JSON files (jsonl/json)
+            run-shards           fan out N parallel OS processes (POLYRUN_SHARD_*; not Ruby threads); optional --merge-coverage / --merge-failures
             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 --; optional --shard-processes M or --workers M (POLYRUN_SHARD_PROCESSES; not POLYRUN_WORKERS) for N×M jobs × processes on this host

data/lib/polyrun/cli/run_shards_command.rb

@@ -2,12 +2,14 @@ require "optparse"
 require "rbconfig"
 
 require_relative "start_bootstrap"
+require_relative "failure_commands"
 require_relative "run_shards_run"
 
 module Polyrun
   class CLI
     module RunShardsCommand
       include StartBootstrap
+      include FailureCommands
       include RunShardsRun
 
       private
@@ -114,10 +116,11 @@ module Polyrun
       # ENV for a worker process: POLYRUN_SHARD_* plus per-shard database URLs from polyrun.yml or DATABASE_URL.
       # When +matrix_total+ > 1 with multiple local workers, sets +POLYRUN_SHARD_MATRIX_INDEX+ / +POLYRUN_SHARD_MATRIX_TOTAL+
       # so {Coverage::Collector} can name fragments uniquely across CI matrix jobs (NxM sharding).
-      def shard_child_env(cfg:, workers:, shard:, matrix_index: nil, matrix_total: nil)
+      def shard_child_env(cfg:, workers:, shard:, matrix_index: nil, matrix_total: nil, failure_fragments: false)
         child_env = ENV.to_h.merge(
           Polyrun::Database::Shard.env_map(shard_index: shard, shard_total: workers)
         )
+        child_env["POLYRUN_FAILURE_FRAGMENTS"] = "1" if failure_fragments
         mt = matrix_total.nil? ? 0 : Integer(matrix_total)
         if mt > 1
           if matrix_index.nil?

data/lib/polyrun/cli/run_shards_parallel_children.rb

@@ -34,7 +34,14 @@ module Polyrun
             return [pids, code]
           end
 
-          child_env = shard_child_env(cfg: cfg, workers: workers, shard: shard, matrix_index: mx, matrix_total: mt)
+          child_env = shard_child_env(
+            cfg: cfg,
+            workers: workers,
+            shard: shard,
+            matrix_index: mx,
+            matrix_total: mt,
+            failure_fragments: ctx[:merge_failures]
+          )
           child_env = child_env.merge("POLYRUN_HOOK_ORCHESTRATOR" => "0")
           child_env = hook_cfg.merge_worker_ruby_env(child_env)
 

data/lib/polyrun/cli/run_shards_plan_boot_phases.rb

@@ -31,7 +31,7 @@ module Polyrun
         costs, strategy, err = run_shards_resolve_costs(o[:timing_path], o[:strategy], o[:timing_granularity])
         return [err, nil] if err
 
-        run_shards_plan_ready_log(o, strategy, cmd, paths_source, items.size)
+        run_shards_plan_ready_log(o, cfg, strategy, cmd, paths_source, items.size)
 
         constraints = load_partition_constraints(pc, o[:constraints_path])
         plan = run_shards_make_plan(items, o[:workers], strategy, o[:seed], costs, constraints, o[:timing_granularity])
@@ -59,12 +59,13 @@ module Polyrun
         [run_t0, head, cmd, cfg, cfg.partition]
       end
 
-      def run_shards_plan_ready_log(o, strategy, cmd, paths_source, item_count)
+      def run_shards_plan_ready_log(o, cfg, strategy, cmd, paths_source, item_count)
         Polyrun::Debug.log_kv(
           run_shards: "ready to partition",
           workers: o[:workers],
           strategy: strategy,
           merge_coverage: o[:merge_coverage],
+          merge_failures: run_shards_merge_failures_flag(o, cfg),
           command: cmd,
           timing_path: o[:timing_path],
           paths_source: paths_source,
@@ -72,6 +73,37 @@ module Polyrun
         )
       end
 
+      def run_shards_merge_failures_flag(o, cfg)
+        return true if o[:merge_failures]
+        return true if %w[1 true yes].include?(ENV["POLYRUN_MERGE_FAILURES"].to_s.downcase)
+
+        rep = cfg.reporting
+        v = rep["merge_failures"] || rep[:merge_failures]
+        v == true || %w[1 true yes].include?(v.to_s.downcase)
+      end
+
+      def run_shards_merge_failures_output_opt(o, cfg)
+        x = o[:merge_failures_output]
+        return x if x && !x.to_s.strip.empty?
+
+        x = ENV["POLYRUN_MERGED_FAILURES_OUT"]
+        return x if x && !x.to_s.strip.empty?
+
+        rep = cfg.reporting
+        rep["merge_failures_output"] || rep[:merge_failures_output]
+      end
+
+      def run_shards_merge_failures_format_opt(o, cfg)
+        x = o[:merge_failures_format]
+        return x if x && !x.to_s.strip.empty?
+
+        x = ENV["POLYRUN_MERGED_FAILURES_FORMAT"]
+        return x if x && !x.to_s.strip.empty?
+
+        rep = cfg.reporting
+        rep["merge_failures_format"] || rep[:merge_failures_format]
+      end
+
       def run_shards_plan_context_hash(o, cmd, cfg, plan, run_t0, parallel, config_path)
         {
           workers: o[:workers],
@@ -83,6 +115,9 @@ module Polyrun
           merge_coverage: o[:merge_coverage],
           merge_output: o[:merge_output],
           merge_format: o[:merge_format],
+          merge_failures: run_shards_merge_failures_flag(o, cfg),
+          merge_failures_output: run_shards_merge_failures_output_opt(o, cfg),
+          merge_failures_format: run_shards_merge_failures_format_opt(o, cfg),
           config_path: config_path
         }
       end

data/lib/polyrun/cli/run_shards_plan_options.rb

@@ -24,7 +24,10 @@ module Polyrun
           timing_granularity: nil,
           merge_coverage: false,
           merge_output: nil,
-          merge_format: nil
+          merge_format: nil,
+          merge_failures: false,
+          merge_failures_output: nil,
+          merge_failures_format: nil
         }
       end
 
@@ -34,8 +37,9 @@ module Polyrun
         end.parse!(head)
       end
 
+      # rubocop:disable Metrics/AbcSize -- one argv block for run-shards
       def run_shards_plan_options_register!(opts, st)
-        opts.banner = "usage: polyrun run-shards [--workers N] [--strategy NAME] [--paths-file P] [--timing P] [--timing-granularity VAL] [--constraints P] [--seed S] [--merge-coverage] [--merge-output P] [--merge-format LIST] [--] <command> [args...]"
+        opts.banner = "usage: polyrun run-shards [--workers N] [--strategy NAME] [--paths-file P] [--timing P] [--timing-granularity VAL] [--constraints P] [--seed S] [--merge-coverage] [--merge-output P] [--merge-format LIST] [--merge-failures] [--merge-failures-output P] [--merge-failures-format jsonl|json] [--] <command> [args...]"
         opts.on("--workers N", Integer) { |v| st[:workers] = v }
         opts.on("--strategy NAME", String) { |v| st[:strategy] = v }
         opts.on("--seed VAL") { |v| st[:seed] = v }
@@ -46,7 +50,11 @@ 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-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 }
       end
+      # rubocop:enable Metrics/AbcSize
     end
   end
 end

data/lib/polyrun/cli/run_shards_run.rb

@@ -25,6 +25,8 @@ module Polyrun
         hook_cfg = Polyrun::Hooks.from_config(ctx[:cfg])
         suite_started = false
         exit_code = 1
+        merged_failures_path = nil
+        merge_failures_errored = false
 
         begin
           env_suite = ENV.to_h.merge(
@@ -60,8 +62,20 @@ module Polyrun
             Polyrun::Log.warn "polyrun run-shards: finished #{pids.size} worker(s)" + (failed.any? ? " (some failed)" : " (exit 0)")
           end
 
+          if ctx[:merge_failures]
+            begin
+              merged_failures_path = merge_failures_after_shards(ctx)
+            rescue Polyrun::Error => e
+              Polyrun::Log.warn e.message.to_s
+              merge_failures_errored = true
+            end
+          end
+
           if failed.any?
-            run_shards_log_failed_reruns(failed, shard_results, ctx[:plan], ctx[:parallel], ctx[:workers], ctx[:cmd])
+            run_shards_log_failed_reruns(
+              failed, shard_results, ctx[:plan], ctx[:parallel], ctx[:workers], ctx[:cmd],
+              merge_failures: ctx[:merge_failures]
+            )
             exit_code = 1
             exit_code = 1 if wait_hook_err != 0
             return exit_code
@@ -69,13 +83,15 @@ module Polyrun
 
           exit_code = run_shards_merge_or_hint_coverage(ctx)
           exit_code = 1 if wait_hook_err != 0 && exit_code == 0
+          exit_code = 1 if merge_failures_errored && exit_code == 0
           exit_code
         ensure
           if suite_started
             env_after = ENV.to_h.merge(
               "POLYRUN_HOOK_ORCHESTRATOR" => "1",
               "POLYRUN_SHARD_TOTAL" => ctx[:workers].to_s,
-              "POLYRUN_SUITE_EXIT_STATUS" => exit_code.to_s
+              "POLYRUN_SUITE_EXIT_STATUS" => exit_code.to_s,
+              "POLYRUN_MERGED_FAILURES_PATH" => merged_failures_path.to_s
             )
             hook_cfg.run_phase_if_enabled(:after_suite, env_after)
           end
@@ -139,7 +155,7 @@ module Polyrun
         0
       end
 
-      def run_shards_log_failed_reruns(failed, shard_results, plan, parallel, workers, cmd)
+      def run_shards_log_failed_reruns(failed, shard_results, plan, parallel, workers, cmd, merge_failures: false)
         exit_by_shard = shard_results.each_with_object({}) { |r, h| h[r[:shard]] = r[:exitstatus] }
         failed_detail = failed.sort.map { |s| "#{s} (exit #{exit_by_shard[s]})" }.join(", ")
         Polyrun::Log.warn "polyrun run-shards: failed shard(s): #{failed_detail}"
@@ -154,6 +170,9 @@ module Polyrun
           rerun << Shellwords.join(cmd + paths)
           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."
+        end
       end
     end
   end

data/lib/polyrun/cli.rb

@@ -28,7 +28,7 @@ module Polyrun
 
     # 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
+      plan prepare merge-coverage merge-failures 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 hook
     ].freeze
@@ -145,6 +145,8 @@ module Polyrun
         cmd_prepare(argv, config_path)
       when "merge-coverage"
         cmd_merge_coverage(argv, config_path)
+      when "merge-failures"
+        cmd_merge_failures(argv, config_path)
       when "report-coverage"
         cmd_report_coverage(argv)
       when "report-junit"

data/lib/polyrun/config.rb

@@ -66,6 +66,11 @@ module Polyrun
     def hooks
       raw["hooks"] || raw[:hooks] || {}
     end
+
+    # Optional +reporting:+ block (merge-failures output paths, etc.).
+    def reporting
+      raw["reporting"] || raw[:reporting] || {}
+    end
   end
 end
 

data/lib/polyrun/coverage/collector_finish.rb

@@ -41,9 +41,10 @@ module Polyrun
       def self.track_blob_for_finish(cfg, blob)
         sharded = ENV["POLYRUN_SHARD_TOTAL"].to_i > 1
         if cfg[:track_files]
-          return Collector.keep_under_root(blob, cfg[:root], cfg[:track_under]) if sharded
+          filtered = TrackFiles.keep_tracked_files(blob, cfg[:root], cfg[:track_files])
+          return filtered if sharded
 
-          TrackFiles.merge_untracked_into_blob(blob, cfg[:root], cfg[:track_files])
+          TrackFiles.merge_untracked_into_blob(filtered, cfg[:root], cfg[:track_files])
         else
           Collector.keep_under_root(blob, cfg[:root], cfg[:track_under])
         end

data/lib/polyrun/coverage/formatter.rb

@@ -106,7 +106,8 @@ module Polyrun
         def write_files(result, output_dir, basename)
           path = File.join(output_dir, "#{basename}.html")
           title = (result.meta && result.meta["title"]) || (result.meta && result.meta[:title]) || "Polyrun coverage"
-          File.write(path, Merge.emit_html(result.coverage_blob, title: title))
+          root = result.meta && (result.meta["polyrun_coverage_root"] || result.meta[:polyrun_coverage_root])
+          File.write(path, Merge.emit_html(result.coverage_blob, title: title, root: root, groups: result.groups))
           {html: path}
         end
       end