polyrun 1.3.0 → 1.4.1

data/lib/polyrun/hooks.rb

@@ -0,0 +1,185 @@
+require "shellwords"
+
+require_relative "log"
+require_relative "hooks/dsl"
+require_relative "hooks/worker_runner"
+require_relative "hooks/worker_shell"
+
+module Polyrun
+  # Shell and Ruby DSL hooks around parallel orchestration, named like RSpec lifecycle callbacks:
+  # +before_suite+ / +after_suite+ (+before(:suite)+ / +after(:suite)+),
+  # +before_shard+ / +after_shard+ (parent process, per partition index),
+  # +before_worker+ / +after_worker+ (inside each worker process, around the test command).
+  #
+  # Configure under +hooks:+ in +polyrun.yml+: shell strings, and/or +ruby:+ path to a Ruby DSL file.
+  # Run manually: +polyrun hook run <phase>+ (see {CLI}).
+  #
+  # Orchestration respects +POLYRUN_HOOKS_DISABLE=1+ (+run_phase_if_enabled+); +polyrun hook run+ always runs {#run_phase}.
+  class Hooks
+    include WorkerShell
+
+    PHASES = %i[
+      before_suite after_suite
+      before_shard after_shard
+      before_worker after_worker
+    ].freeze
+
+    attr_reader :ruby_file
+
+    def self.disabled?
+      v = ENV["POLYRUN_HOOKS_DISABLE"].to_s.downcase
+      %w[1 true yes].include?(v)
+    end
+
+    # When +POLYRUN_SHARD_TOTAL+ is greater than 1 (+ci-shard-run+ matrix), suite hooks are skipped by default; set
+    # +POLYRUN_HOOKS_SUITE_PER_MATRIX_JOB=1+ to run +before_suite+ / +after_suite+ on every matrix job (legacy).
+    def self.suite_per_matrix_job?
+      v = ENV["POLYRUN_HOOKS_SUITE_PER_MATRIX_JOB"].to_s.downcase
+      %w[1 true yes].include?(v)
+    end
+
+    def self.from_config(cfg)
+      raw = cfg.respond_to?(:hooks) ? cfg.hooks : {}
+      new(raw.is_a?(Hash) ? raw : {})
+    end
+
+    # Maps CLI or YAML-style names (+before_suite+, +"before(:suite)"+) to a phase symbol or +nil+.
+    def self.parse_phase(str)
+      new({}).send(:canonical_key, str)
+    end
+
+    # @param raw [Hash] +hooks+ block from YAML
+    def initialize(raw)
+      @ruby_file = extract_ruby_file(raw)
+      h = {}
+      raw.each do |k, v|
+        next if %w[ruby ruby_file].include?(k.to_s)
+
+        ck = canonical_key(k)
+        next if ck.nil?
+
+        h[ck] = v
+      end
+      @raw = h.freeze
+      @ruby_registry_loaded = false
+      @ruby_registry = nil
+    end
+
+    def empty?
+      no_shell = PHASES.all? { |p| commands_for(p).empty? }
+      return false unless no_shell
+
+      return true if @ruby_file.nil? || @ruby_file.to_s.strip.empty?
+      return true unless File.file?(File.expand_path(@ruby_file, Dir.pwd))
+
+      reg = ruby_registry
+      reg.nil? || reg.empty?
+    end
+
+    def worker_hooks?
+      return true if commands_for(:before_worker).any? || commands_for(:after_worker).any?
+
+      !!ruby_registry&.worker_hooks?
+    end
+
+    # Merges +POLYRUN_HOOKS_RUBY_FILE+ when a DSL file is configured (for worker +ruby -e+).
+    def merge_worker_ruby_env(env)
+      return env unless @ruby_file
+      abs = File.expand_path(@ruby_file, Dir.pwd)
+      return env unless File.file?(abs)
+
+      env.merge("POLYRUN_HOOKS_RUBY_FILE" => abs)
+    end
+
+    # @param phase [Symbol]
+    # @return [Array<String>]
+    def commands_for(phase)
+      v = @raw[phase.to_sym]
+      case v
+      when nil then []
+      when Array then v.map(&:to_s).map(&:strip).reject(&:empty?)
+      else
+        s = v.to_s.strip
+        s.empty? ? [] : [s]
+      end
+    end
+
+    # Runs Ruby DSL blocks (if any), then shell commands for +phase+.
+    # @return [Integer] exit code (0 if no commands)
+    def run_phase(phase, env)
+      return 0 unless PHASES.include?(phase.to_sym)
+
+      merged = stringify_env_for_hook(env).merge(
+        "POLYRUN_HOOK_PHASE" => phase.to_s,
+        "POLYRUN_HOOK" => "1"
+      )
+
+      reg = ruby_registry
+      if reg&.any?(phase)
+        begin
+          reg.run(phase, merged)
+        rescue => e
+          Polyrun::Log.warn "polyrun hooks: #{phase} ruby hook failed: #{e.class}: #{e.message}"
+          return 1
+        end
+      end
+
+      commands_for(phase).each do |cmd|
+        ok = system(merged, "sh", "-c", cmd)
+        return $?.exitstatus unless ok
+      end
+      0
+    end
+
+    # Like {#run_phase}, but no-ops when {disabled?} (+POLYRUN_HOOKS_DISABLE=1+). Used by run-shards / ci-shard orchestration.
+    def run_phase_if_enabled(phase, env)
+      return 0 if self.class.disabled?
+
+      run_phase(phase, env)
+    end
+
+    private
+
+    def extract_ruby_file(raw)
+      v = raw["ruby"] || raw[:ruby] || raw["ruby_file"] || raw[:ruby_file]
+      return nil if v.nil?
+
+      s = v.to_s.strip
+      s.empty? ? nil : s
+    end
+
+    def ruby_registry
+      return @ruby_registry if @ruby_registry_loaded
+
+      @ruby_registry_loaded = true
+      @ruby_registry = Dsl.load_registry(@ruby_file)
+    end
+
+    def stringify_env_for_hook(env)
+      h = {}
+      env.each { |k, v| h[k.to_s] = v }
+      h
+    end
+
+    # Accept RSpec-style quoted keys from YAML, e.g. +"before(:suite)"+.
+    def canonical_key(k)
+      s = k.to_s.strip
+      sym = if s.match?(/\Abefore\(\s*:suite\s*\)\z/i)
+        :before_suite
+      elsif s.match?(/\Aafter\(\s*:suite\s*\)\z/i)
+        :after_suite
+      elsif s.match?(/\Abefore\(\s*:all\s*\)\z/i)
+        :before_shard
+      elsif s.match?(/\Aafter\(\s*:all\s*\)\z/i)
+        :after_shard
+      elsif s.match?(/\Abefore\(\s*:each\s*\)\z/i)
+        :before_worker
+      elsif s.match?(/\Aafter\(\s*:each\s*\)\z/i)
+        :after_worker
+      else
+        s.downcase.tr("-", "_").to_sym
+      end
+      PHASES.include?(sym) ? sym : nil
+    end
+  end
+end

data/lib/polyrun/reporting/failure_merge.rb

@@ -0,0 +1,135 @@
+require "json"
+require "fileutils"
+
+module Polyrun
+  module Reporting
+    # Merge per-worker / per-shard failure fragments (JSONL or RSpec JSON) into one report.
+    # Fragment basenames align with {Coverage::CollectorFragmentMeta} (worker index and optional matrix shard).
+    module FailureMerge
+      DEFAULT_FRAGMENT_DIR = "tmp/polyrun_failures".freeze
+      FRAGMENT_GLOB = "polyrun-failure-fragment-*.jsonl".freeze
+
+      module_function
+
+      def default_fragment_glob(dir = nil)
+        root = File.expand_path(dir || DEFAULT_FRAGMENT_DIR, Dir.pwd)
+        File.join(root, FRAGMENT_GLOB)
+      end
+
+      def merge_fragment_paths(quiet: false)
+        p = default_fragment_glob
+        Dir.glob(p).sort.tap do |paths|
+          Polyrun::Log.warn "merge-failures: no files matched #{p}" if paths.empty? && !quiet
+        end
+      end
+
+      # @param paths [Array<String>] fragment paths (.jsonl and/or RSpec --format json outputs)
+      # @param format [String] "jsonl" or "json"
+      # @param output [String] destination path
+      # @return [Integer] count of failure rows merged
+      def merge_files!(paths, output:, format: "jsonl")
+        fmt = format.to_s.downcase
+        rows = collect_rows(paths)
+        out_abs = File.expand_path(output)
+        FileUtils.mkdir_p(File.dirname(out_abs))
+        case fmt
+        when "json"
+          doc = {
+            "meta" => {
+              "polyrun_merge" => true,
+              "inputs" => paths.map { |p| File.expand_path(p) },
+              "failure_count" => rows.size
+            },
+            "failures" => rows
+          }
+          File.write(out_abs, JSON.generate(doc))
+        when "jsonl"
+          File.write(out_abs, rows.map { |h| JSON.generate(h) }.join("\n") + (rows.empty? ? "" : "\n"))
+        else
+          raise Polyrun::Error, "merge-failures: unknown format #{fmt.inspect} (use jsonl or json)"
+        end
+        rows.size
+      end
+
+      def collect_rows(paths)
+        rows = []
+        paths.each do |p|
+          rows.concat(rows_from_path(p))
+        end
+        rows
+      end
+
+      def rows_from_path(path)
+        ext = File.extname(path).downcase
+        if ext == ".jsonl"
+          return rows_from_jsonl_file(path)
+        end
+
+        text = File.read(path)
+        data =
+          begin
+            JSON.parse(text)
+          rescue JSON::ParserError => e
+            raise Polyrun::Error, "merge-failures: #{path} is not valid JSON: #{e.message}"
+          end
+        if data.is_a?(Hash) && data["examples"].is_a?(Array)
+          return failures_from_rspec_examples(data["examples"])
+        end
+
+        hint =
+          if data.is_a?(Hash)
+            keys = data.keys
+            "got JSON object with keys: #{keys.take(12).join(", ")}" + ((keys.size > 12) ? ", …" : "")
+          else
+            "got #{data.class}"
+          end
+        raise Polyrun::Error,
+          "merge-failures: #{path} is not RSpec JSON (expected top-level \"examples\" array). #{hint}. " \
+          "Use RSpec --format json, or polyrun failure JSONL (.jsonl fragments)."
+      end
+
+      def rows_from_jsonl_file(path)
+        acc = []
+        File.readlines(path, chomp: true).each_with_index do |line, idx|
+          line = line.strip
+          next if line.empty?
+
+          acc << parse_jsonl_line!(path, idx + 1, line)
+        end
+        acc
+      end
+
+      def parse_jsonl_line!(path, line_number, line)
+        JSON.parse(line)
+      rescue JSON::ParserError => e
+        raise Polyrun::Error,
+          "merge-failures: invalid JSONL at #{path} line #{line_number}: #{e.message}"
+      end
+
+      def failures_from_rspec_examples(examples)
+        examples.each_with_object([]) do |ex, acc|
+          next unless ex.is_a?(Hash)
+          next unless ex["status"].to_s == "failed"
+
+          acc << rspec_example_to_row(ex)
+        end
+      end
+
+      def rspec_example_to_row(ex)
+        ex = ex.transform_keys(&:to_s)
+        exc = ex["exception"] || {}
+        exc = exc.transform_keys(&:to_s) if exc.is_a?(Hash)
+        {
+          "id" => ex["id"],
+          "full_description" => ex["full_description"],
+          "location" => (ex["file_path"] && ex["line_number"]) ? "#{ex["file_path"]}:#{ex["line_number"]}" : ex["full_description"],
+          "file_path" => ex["file_path"],
+          "line_number" => ex["line_number"],
+          "message" => exc["message"] || ex["full_description"],
+          "exception_class" => exc["class"],
+          "source" => "rspec_json"
+        }.compact
+      end
+    end
+  end
+end

data/lib/polyrun/reporting/rspec_failure_fragment_formatter.rb

@@ -0,0 +1,95 @@
+require "json"
+require "fileutils"
+
+module Polyrun
+  module Reporting
+    # RSpec formatter: appends one JSON object per failed example to the shard fragment file.
+    # Enable via +Polyrun::RSpec.install_failure_fragments!+ and +POLYRUN_FAILURE_FRAGMENTS=1+ (set by run-shards --merge-failures).
+    #
+    # Output: +tmp/polyrun_failures/polyrun-failure-fragment-<workerN|shardM-workerN>.jsonl+
+    # (same basename rules as {Coverage::CollectorFragmentMeta}.)
+    class RspecFailureFragmentFormatter
+      ::RSpec::Core::Formatters.register self, :start, :example_failed
+
+      attr_reader :output
+
+      def initialize(output)
+        @output = output
+        @path = fragment_path
+      end
+
+      def start(_notification)
+        FileUtils.mkdir_p(File.dirname(@path))
+        File.write(@path, "")
+      end
+
+      def example_failed(notification)
+        ex = notification.example
+        exc = notification.exception
+        row = {
+          "id" => ex.id,
+          "full_description" => ex.full_description,
+          "location" => ex.location,
+          "file_path" => ex.file_path,
+          "line_number" => example_line_number(ex),
+          "message" => exc.message.to_s,
+          "exception_class" => exc.class.name,
+          "polyrun_shard_index" => ENV["POLYRUN_SHARD_INDEX"],
+          "polyrun_shard_total" => ENV["POLYRUN_SHARD_TOTAL"],
+          "polyrun_shard_matrix_index" => matrix_env_or_nil("POLYRUN_SHARD_MATRIX_INDEX"),
+          "polyrun_shard_matrix_total" => matrix_env_or_nil("POLYRUN_SHARD_MATRIX_TOTAL"),
+          "rspec_seed" => seed_if_known,
+          "rspec_order" => order_if_known
+        }
+        trim_backtrace!(row, exc)
+        File.open(@path, "a") { |f| f.puts(JSON.generate(row.compact)) }
+      end
+
+      private
+
+      def example_line_number(ex)
+        return ex.line_number if ex.respond_to?(:line_number)
+
+        ex.metadata[:line_number]
+      end
+
+      def fragment_path
+        dir = ENV.fetch("POLYRUN_FAILURE_FRAGMENT_DIR", FailureMerge::DEFAULT_FRAGMENT_DIR)
+        base = Polyrun::Coverage::CollectorFragmentMeta.fragment_default_basename_from_env
+        File.expand_path(File.join(dir, "polyrun-failure-fragment-#{base}.jsonl"))
+      end
+
+      def matrix_env_or_nil(name)
+        v = ENV[name]
+        return nil if v.nil? || v.to_s.strip.empty?
+
+        v
+      end
+
+      def seed_if_known
+        return unless defined?(::RSpec) && ::RSpec.respond_to?(:configuration)
+
+        ::RSpec.configuration.seed
+      rescue
+        nil
+      end
+
+      def order_if_known
+        return unless defined?(::RSpec) && ::RSpec.respond_to?(:configuration)
+
+        ::RSpec.configuration.order.to_s
+      rescue
+        nil
+      end
+
+      MAX_BT = 20
+
+      def trim_backtrace!(row, exc)
+        bt = exc.backtrace
+        return unless bt.is_a?(Array) && bt.any?
+
+        row["backtrace"] = bt.first(MAX_BT)
+      end
+    end
+  end
+end

data/lib/polyrun/rspec.rb

@@ -30,5 +30,19 @@ module Polyrun
         config.add_formatter fmt
       end
     end
+
+    # Per-worker failure JSONL fragments for +polyrun run-shards --merge-failures+ (parity with coverage shards).
+    # Requires +POLYRUN_FAILURE_FRAGMENTS=1+ (set by the parent when --merge-failures is used) unless +only_if+ overrides.
+    # Writes +tmp/polyrun_failures/polyrun-failure-fragment-*.jsonl+ (override dir with +POLYRUN_FAILURE_FRAGMENT_DIR+).
+    def install_failure_fragments!(only_if: nil)
+      pred = only_if || -> { %w[1 true yes].include?(ENV["POLYRUN_FAILURE_FRAGMENTS"].to_s.downcase) }
+      return unless pred.call
+
+      require "rspec/core"
+      require_relative "reporting/rspec_failure_fragment_formatter"
+      ::RSpec.configure do |config|
+        config.add_formatter Polyrun::Reporting::RspecFailureFragmentFormatter
+      end
+    end
   end
 end

data/lib/polyrun/version.rb

@@ -1,3 +1,3 @@
 module Polyrun
-  VERSION = "1.3.0"
+  VERSION = "1.4.1"
 end

data/lib/polyrun.rb

@@ -25,6 +25,7 @@ require_relative "polyrun/database/shard"
 require_relative "polyrun/database/url_builder"
 require_relative "polyrun/database/provision"
 require_relative "polyrun/database/clone_shards"
+require_relative "polyrun/hooks"
 require_relative "polyrun/env/ci"
 require_relative "polyrun/timing/merge"
 require_relative "polyrun/timing/summary"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: polyrun
 version: !ruby/object:Gem::Version
-  version: 1.3.0
+  version: 1.4.1
 platform: ruby
 authors:
 - Andrei Makarov
@@ -166,6 +166,7 @@ files:
 - docs/SETUP_PROFILE.md
 - lib/polyrun.rb
 - lib/polyrun/cli.rb
+- lib/polyrun/cli/ci_shard_hooks.rb
 - lib/polyrun/cli/ci_shard_run_command.rb
 - lib/polyrun/cli/ci_shard_run_parse.rb
 - lib/polyrun/cli/config_command.rb
@@ -174,8 +175,10 @@ files:
 - lib/polyrun/cli/database_commands.rb
 - lib/polyrun/cli/default_run.rb
 - lib/polyrun/cli/env_commands.rb
+- lib/polyrun/cli/failure_commands.rb
 - lib/polyrun/cli/help.rb
 - lib/polyrun/cli/helpers.rb
+- lib/polyrun/cli/hooks_command.rb
 - lib/polyrun/cli/init_command.rb
 - lib/polyrun/cli/plan_command.rb
 - lib/polyrun/cli/prepare_command.rb
@@ -184,6 +187,7 @@ files:
 - lib/polyrun/cli/quick_command.rb
 - lib/polyrun/cli/report_commands.rb
 - lib/polyrun/cli/run_shards_command.rb
+- lib/polyrun/cli/run_shards_parallel_children.rb
 - lib/polyrun/cli/run_shards_plan_boot_phases.rb
 - lib/polyrun/cli/run_shards_plan_options.rb
 - lib/polyrun/cli/run_shards_planning.rb
@@ -225,6 +229,10 @@ files:
 - lib/polyrun/database/url_builder/template_prepare.rb
 - lib/polyrun/debug.rb
 - lib/polyrun/env/ci.rb
+- lib/polyrun/hooks.rb
+- lib/polyrun/hooks/dsl.rb
+- lib/polyrun/hooks/worker_runner.rb
+- lib/polyrun/hooks/worker_shell.rb
 - lib/polyrun/log.rb
 - lib/polyrun/minitest.rb
 - lib/polyrun/partition/constraints.rb
@@ -251,8 +259,10 @@ files:
 - lib/polyrun/quick/reporter.rb
 - lib/polyrun/quick/runner.rb
 - lib/polyrun/railtie.rb
+- lib/polyrun/reporting/failure_merge.rb
 - lib/polyrun/reporting/junit.rb
 - lib/polyrun/reporting/junit_emit.rb
+- lib/polyrun/reporting/rspec_failure_fragment_formatter.rb
 - lib/polyrun/reporting/rspec_junit.rb
 - lib/polyrun/rspec.rb
 - lib/polyrun/templates/POLYRUN.md