polyrun 1.3.0 → 1.4.1

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

@@ -2,12 +2,14 @@ require "shellwords"
 require "rbconfig"
 
 require_relative "run_shards_planning"
+require_relative "run_shards_parallel_children"
 
 module Polyrun
   class CLI
     # Partition + spawn workers for `polyrun run-shards` (keeps {RunShardsCommand} file small).
     module RunShardsRun
       include RunShardsPlanning
+      include RunShardsParallelChildren
 
       private
 
@@ -18,59 +20,84 @@ module Polyrun
         run_shards_workers_and_merge(ctx)
       end
 
+      # rubocop:disable Metrics/AbcSize -- orchestration: hooks, merge, worker failures
       def run_shards_workers_and_merge(ctx)
-        pids = run_shards_spawn_workers(ctx)
-        return 1 if pids.empty?
-
-        run_shards_warn_interleaved(ctx[:parallel], pids.size)
+        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(
+            "POLYRUN_HOOK_ORCHESTRATOR" => "1",
+            "POLYRUN_SHARD_TOTAL" => ctx[:workers].to_s
+          )
+          code = hook_cfg.run_phase_if_enabled(:before_suite, env_suite)
+          return code if code != 0
+
+          suite_started = true
+
+          pids, spawn_err = run_shards_spawn_workers(ctx, hook_cfg)
+          if spawn_err
+            exit_code = spawn_err
+            return spawn_err
+          end
+          if pids.empty?
+            exit_code = 1
+            return 1
+          end
 
-        shard_results = run_shards_wait_all_children(pids)
-        failed = shard_results.reject { |r| r[:success] }.map { |r| r[:shard] }
+          run_shards_warn_interleaved(ctx[:parallel], pids.size)
 
-        Polyrun::Debug.log(format(
-          "run-shards: workers wall time since start: %.3fs",
-          Process.clock_gettime(Process::CLOCK_MONOTONIC) - ctx[:run_t0]
-        ))
+          shard_results, wait_hook_err = run_shards_wait_all_children(pids, hook_cfg, ctx)
+          failed = shard_results.reject { |r| r[:success] }.map { |r| r[:shard] }
 
-        if ctx[:parallel]
-          Polyrun::Log.warn "polyrun run-shards: finished #{pids.size} worker(s)" + (failed.any? ? " (some failed)" : " (exit 0)")
-        end
+          Polyrun::Debug.log(format(
+            "run-shards: workers wall time since start: %.3fs",
+            Process.clock_gettime(Process::CLOCK_MONOTONIC) - ctx[:run_t0]
+          ))
 
-        if failed.any?
-          run_shards_log_failed_reruns(failed, shard_results, ctx[:plan], ctx[:parallel], ctx[:workers], ctx[:cmd])
-          return 1
-        end
-
-        run_shards_merge_or_hint_coverage(ctx)
-      end
+          if ctx[:parallel]
+            Polyrun::Log.warn "polyrun run-shards: finished #{pids.size} worker(s)" + (failed.any? ? " (some failed)" : " (exit 0)")
+          end
 
-      def run_shards_spawn_workers(ctx)
-        workers = ctx[:workers]
-        cmd = ctx[:cmd]
-        cfg = ctx[:cfg]
-        plan = ctx[:plan]
-        parallel = ctx[:parallel]
-        mx = ctx[:matrix_shard_index]
-        mt = ctx[:matrix_shard_total]
-
-        pids = []
-        workers.times do |shard|
-          paths = plan.shard(shard)
-          if paths.empty?
-            Polyrun::Log.warn "polyrun run-shards: shard #{shard} skipped (no paths)" if @verbose || parallel
-            next
+          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
 
-          child_env = shard_child_env(cfg: cfg, workers: workers, shard: shard, matrix_index: mx, matrix_total: mt)
+          if failed.any?
+            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
+          end
 
-          Polyrun::Log.warn "polyrun run-shards: shard #{shard} → #{paths.size} file(s)" if @verbose
-          pid = Process.spawn(child_env, *cmd, *paths)
-          pids << {pid: pid, shard: shard}
-          Polyrun::Debug.log("[parent pid=#{$$}] run-shards: Process.spawn shard=#{shard} child_pid=#{pid} spec_files=#{paths.size}")
-          Polyrun::Log.warn "polyrun run-shards: started shard #{shard} pid=#{pid} (#{paths.size} file(s))" if parallel
+          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_MERGED_FAILURES_PATH" => merged_failures_path.to_s
+            )
+            hook_cfg.run_phase_if_enabled(:after_suite, env_after)
+          end
         end
-        pids
       end
+      # rubocop:enable Metrics/AbcSize
 
       def run_shards_warn_interleaved(parallel, pid_count)
         return unless parallel && pid_count > 1
@@ -79,27 +106,6 @@ module Polyrun
         Polyrun::Log.warn "polyrun run-shards: each worker prints its own summary line; the last \"N examples\" line is not a total across shards."
       end
 
-      def run_shards_wait_all_children(pids)
-        shard_results = []
-        Polyrun::Debug.time("Process.wait (#{pids.size} worker process(es))") do
-          pids.each do |h|
-            Process.wait(h[:pid])
-            exitstatus = $?.exitstatus
-            ok = $?.success?
-            Polyrun::Debug.log("[parent pid=#{$$}] run-shards: Process.wait child_pid=#{h[:pid]} shard=#{h[:shard]} exit=#{exitstatus} success=#{ok}")
-            shard_results << {shard: h[:shard], exitstatus: exitstatus, success: ok}
-          end
-        rescue Interrupt
-          # Do not trap SIGINT: Process.wait raises Interrupt; a trap races and prints Interrupt + SystemExit traces.
-          run_shards_shutdown_on_signal!(pids, 130)
-        rescue SignalException => e
-          raise unless e.signm == "SIGTERM"
-
-          run_shards_shutdown_on_signal!(pids, 143)
-        end
-        shard_results
-      end
-
       # Best-effort worker teardown then exit. Does not return.
       def run_shards_shutdown_on_signal!(pids, code)
         run_shards_terminate_children!(pids)
@@ -149,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}"
@@ -164,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

@@ -16,6 +16,7 @@ require_relative "cli/ci_shard_run_parse"
 require_relative "cli/ci_shard_run_command"
 require_relative "cli/config_command"
 require_relative "cli/default_run"
+require_relative "cli/hooks_command"
 require_relative "cli/help"
 
 module Polyrun
@@ -27,9 +28,9 @@ 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
+      run-shards parallel-rspec start build-paths init queue quick hook
     ].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.
@@ -53,6 +54,7 @@ module Polyrun
     include CiShardRunCommand
     include ConfigCommand
     include DefaultRun
+    include HooksCommand
     include Help
 
     def self.run(argv = ARGV)
@@ -143,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"
@@ -177,6 +181,8 @@ module Polyrun
         cmd_queue(argv)
       when "quick"
         cmd_quick(argv)
+      when "hook"
+        cmd_hook(argv, config_path)
       else
         Polyrun::Log.warn "unknown command: #{command}"
         2

data/lib/polyrun/config.rb

@@ -61,6 +61,16 @@ module Polyrun
     def version
       raw["version"] || raw[:version]
     end
+
+    # Optional +hooks:+ block for +run-shards+ / +parallel-rspec+ / +ci-shard-*+ (see {Hooks}).
+    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/hooks/dsl.rb

@@ -0,0 +1,128 @@
+require "monitor"
+
+require_relative "../log"
+
+module Polyrun
+  class Hooks
+    # Ruby DSL for +hooks.ruby+ / +hooks.ruby_file+ in +polyrun.yml+ (see README).
+    #
+    # Example file (+config/polyrun_hooks.rb+):
+    #
+    #   before(:suite) { |env| puts env["POLYRUN_HOOK_PHASE"] }
+    #   after(:each) { |env| }
+    #
+    # Blocks receive a hash with string keys (same env as shell hooks).
+    module Dsl
+      class Registry
+        def initialize
+          @phases = Hash.new { |h, k| h[k] = [] }
+        end
+
+        def add(phase, proc)
+          @phases[phase.to_sym] << proc
+        end
+
+        # @param env [Hash] string-keyed env
+        def run(phase, env)
+          @phases[phase.to_sym].each { |pr| pr.call(env) }
+        end
+
+        def any?(phase)
+          @phases[phase.to_sym].any?
+        end
+
+        def empty?
+          @phases.values.all?(&:empty?)
+        end
+
+        def worker_hooks?
+          any?(:before_worker) || any?(:after_worker)
+        end
+      end
+
+      # Evaluates a hook file with +before+ / +after+ (+before(:suite)+, etc.).
+      class FileContext
+        def initialize(path)
+          @path = path
+          @registry = Registry.new
+        end
+
+        attr_reader :registry
+
+        def load_file
+          instance_eval(File.read(@path), @path)
+          @registry
+        end
+
+        def before(sym, &block)
+          @registry.add(map_before(sym), block)
+        end
+
+        def after(sym, &block)
+          @registry.add(map_after(sym), block)
+        end
+
+        private
+
+        def map_before(sym)
+          case sym.to_sym
+          when :suite then :before_suite
+          when :all then :before_shard
+          when :each then :before_worker
+          else
+            raise ArgumentError, "hooks DSL: before(#{sym.inspect}) — use :suite, :all, or :each"
+          end
+        end
+
+        def map_after(sym)
+          case sym.to_sym
+          when :suite then :after_suite
+          when :all then :after_shard
+          when :each then :after_worker
+          else
+            raise ArgumentError, "hooks DSL: after(#{sym.inspect}) — use :suite, :all, or :each"
+          end
+        end
+      end
+
+      class << self
+        # @return [Registry, nil]
+        def load_registry(path)
+          return nil if path.nil? || path.to_s.strip.empty?
+
+          full = File.expand_path(path.to_s, Dir.pwd)
+          return nil unless File.file?(full)
+
+          mtime = File.mtime(full)
+          cache_mu.synchronize do
+            hit = registry_cache[full]
+            return hit[:registry] if hit && hit[:mtime] == mtime
+
+            reg = FileContext.new(full).load_file
+            registry_cache[full] = {mtime: mtime, registry: reg}
+            reg
+          end
+        rescue => e
+          Polyrun::Log.warn "polyrun hooks: failed to load #{full}: #{e.class}: #{e.message}"
+          nil
+        end
+
+        def clear_cache!
+          cache_mu.synchronize { registry_cache.clear }
+        end
+
+        private
+
+        # rubocop:disable ThreadSafety/ClassInstanceVariable -- single-threaded hook load; Monitor protects cache
+        def cache_mu
+          @cache_mu ||= Monitor.new
+        end
+
+        def registry_cache
+          @registry_cache ||= {}
+        end
+        # rubocop:enable ThreadSafety/ClassInstanceVariable
+      end
+    end
+  end
+end

data/lib/polyrun/hooks/worker_runner.rb

@@ -0,0 +1,27 @@
+require_relative "../log"
+
+module Polyrun
+  class Hooks
+    # Invoked by worker shell wrapper (+ruby -e+). Requires +POLYRUN_HOOKS_RUBY_FILE+.
+    module WorkerRunner
+      module_function
+
+      # @return [Integer] exit code (0 on success)
+      def run!(phase)
+        phase = phase.to_sym
+        path = ENV["POLYRUN_HOOKS_RUBY_FILE"]
+        return 0 if path.nil? || path.empty?
+
+        registry = Dsl.load_registry(path)
+        return 0 if registry.nil? || !registry.any?(phase)
+
+        env = ENV.to_h
+        registry.run(phase, env)
+        0
+      rescue => e
+        Polyrun::Log.warn "polyrun hooks worker #{phase}: #{e.class}: #{e.message}"
+        1
+      end
+    end
+  end
+end

data/lib/polyrun/hooks/worker_shell.rb

@@ -0,0 +1,50 @@
+require "shellwords"
+require "rbconfig"
+
+module Polyrun
+  class Hooks
+    # Builds +sh -c+ script for worker processes (shell + Ruby +before_worker+ / +after_worker+).
+    module WorkerShell
+      # @param cmd [Array<String>] argv before paths
+      # @param paths [Array<String>]
+      # @return [String] shell script body for +sh -c+ (worker process)
+      # rubocop:disable Metrics/AbcSize -- shell + ruby worker hook branches
+      def build_worker_shell_script(cmd, paths)
+        main = Shellwords.join(cmd + paths)
+        rb = RbConfig.ruby
+        bw_shell = commands_for(:before_worker)
+        aw_shell = commands_for(:after_worker)
+        bw_ruby = ruby_registry&.any?(:before_worker)
+        aw_ruby = ruby_registry&.any?(:after_worker)
+
+        lines = []
+        lines << "export POLYRUN_HOOK_PHASE=before_worker"
+        if bw_ruby || bw_shell.any?
+          lines << "set -e"
+          lines << worker_ruby_line(rb, :before_worker) if bw_ruby
+          bw_shell.each { |c| lines << c }
+        end
+        lines << "set +e"
+        lines << main
+        lines << "ec=$?"
+        lines << "export POLYRUN_HOOK_PHASE=after_worker"
+        if aw_ruby || aw_shell.any?
+          lines << "set +e"
+          aw_shell.each { |c| lines << "( #{c} ) || true" }
+          lines << worker_ruby_line(rb, :after_worker, wrap_allow_fail: true) if aw_ruby
+        end
+        lines << "exit $ec"
+        lines.join("\n")
+      end
+      # rubocop:enable Metrics/AbcSize
+
+      private
+
+      def worker_ruby_line(rb_exe, phase, wrap_allow_fail: false)
+        code = %(require "polyrun"; Polyrun::Hooks::WorkerRunner.run!(:#{phase}))
+        line = "#{rb_exe} -e #{Shellwords.escape(code)}"
+        wrap_allow_fail ? "( #{line} ) || true" : line
+      end
+    end
+  end
+end