polyrun 2.1.2 → 2.2.0

data/lib/polyrun/reporting/junit.rb

@@ -14,26 +14,26 @@ module Polyrun
     module Junit
       module_function
 
-      def write_from_json_file(json_path, output_path:)
+      def write_from_json_file(json_path, output_path:, format: "xml")
         data = JSON.parse(File.read(json_path))
-        write_from_hash(data, output_path: output_path)
+        write_from_hash(data, output_path: output_path, format: format)
       end
 
       # Merge several RSpec JSON outputs (parallel shards) by concatenating +examples+.
-      def merge_rspec_json_files(paths, output_path:)
+      def merge_rspec_json_files(paths, output_path:, format: "xml")
         merged = {"examples" => []}
         paths.each do |p|
           data = JSON.parse(File.read(p))
           merged["examples"].concat(data["examples"] || [])
         end
         merged["summary"] = {"summary_line" => "merged #{paths.size} RSpec JSON file(s)"}
-        write_from_hash(merged, output_path: output_path)
+        write_from_hash(merged, output_path: output_path, format: format)
       end
 
-      def write_from_hash(data, output_path:)
+      def write_from_hash(data, output_path:, format: "xml")
         doc = parse_input(data)
-        xml = emit_xml(doc)
-        File.write(output_path, xml)
+        body = render(doc, format: format)
+        File.write(output_path, body)
         output_path
       end
 
@@ -123,3 +123,4 @@ module Polyrun
 end
 
 require_relative "junit_emit"
+require_relative "junit_report"

data/lib/polyrun/reporting/junit_report.rb

@@ -0,0 +1,87 @@
+require "json"
+
+require_relative "../export/csv"
+require_relative "../export/markdown"
+
+module Polyrun
+  module Reporting
+    module Junit
+      CSV_HEADERS = %w[classname name status time_seconds failure_message].freeze
+      MARKDOWN_HEADERS = %w[classname name status time_seconds].freeze
+
+      module_function
+
+      def render(doc, format: "xml")
+        case format.to_s.downcase
+        when "xml" then emit_xml(doc)
+        when "csv" then emit_csv(doc)
+        when "markdown", "md" then emit_markdown(doc)
+        else
+          raise Polyrun::Error, "report-junit: unknown format #{format.inspect} (use xml, csv, or markdown)"
+        end
+      end
+
+      def emit_csv(doc)
+        rows = Array(doc["testcases"]).map { |testcase| csv_row(testcase) }
+        Export::Csv.generate(CSV_HEADERS, rows)
+      end
+
+      def csv_row(testcase)
+        testcase = testcase.transform_keys(&:to_s)
+        failure = testcase["failure"] || {}
+        failure = failure.transform_keys(&:to_s) if failure.is_a?(Hash)
+        [
+          testcase["classname"],
+          testcase["name"],
+          status_of(testcase),
+          format_float(testcase["time"] || 0),
+          failure["message"]
+        ]
+      end
+
+      def emit_markdown(doc)
+        cases = Array(doc["testcases"])
+        sections = [
+          markdown_summary_section(doc, cases),
+          markdown_testcases_section(cases)
+        ]
+        failure_section = markdown_failures_section(cases)
+        sections << failure_section if failure_section
+        Export::Markdown.document(doc["name"].to_s, sections)
+      end
+
+      def markdown_summary_section(doc, cases)
+        total_time = cases.sum { |testcase| (testcase["time"] || testcase[:time] || 0).to_f }
+        summary_rows = [
+          ["tests", cases.size],
+          ["failures", cases.count { |testcase| status_of(testcase) == "failed" }],
+          ["errors", cases.count { |testcase| status_of(testcase) == "error" }],
+          ["skipped", cases.count { |testcase| %w[pending skipped].include?(status_of(testcase)) }],
+          ["time_seconds", format_float(total_time)],
+          ["hostname", doc["hostname"]]
+        ]
+        {heading: "Summary", headers: %w[metric value], rows: summary_rows}
+      end
+
+      def markdown_testcases_section(cases)
+        testcase_rows = cases.map do |testcase|
+          testcase = testcase.transform_keys(&:to_s)
+          [testcase["classname"], testcase["name"], status_of(testcase), format_float(testcase["time"] || 0)]
+        end
+        {heading: "Test cases", headers: MARKDOWN_HEADERS, rows: testcase_rows}
+      end
+
+      def markdown_failures_section(cases)
+        failed = cases.select { |testcase| %w[failed error].include?(status_of(testcase)) }
+        return if failed.empty?
+
+        failure_rows = failed.map do |testcase|
+          testcase = testcase.transform_keys(&:to_s)
+          failure = (testcase["failure"] || {}).transform_keys(&:to_s)
+          [testcase["name"], status_of(testcase), failure["message"], failure["body"]]
+        end
+        {heading: "Failures", headers: %w[name status message body], rows: failure_rows}
+      end
+    end
+  end
+end

data/lib/polyrun/rspec/example_debug.rb

@@ -0,0 +1,158 @@
+require "logger"
+require "timeout"
+require_relative "example_debug_instrumentation"
+
+module Polyrun
+  module RSpec
+    # Per-example RSpec debugging for local investigation (SQL, TracePoint, timeouts).
+    #
+    # +POLYRUN_EXAMPLE_DEBUG=1+ enables installers; +DEBUG=1+ / +POLYRUN_DEBUG=1+ trace orchestration only.
+    # +POLYRUN_DEBUG_SQL=1+ or legacy +DEBUG_SQL=1+ logs mutating SQL.
+    # +POLYRUN_DEBUG_TRACE=1+ or legacy +DEBUG_TRACE=1+ traces :call/:raise under the app root.
+    # +DEBUG_LOG_LEVEL+ accepts Ruby Logger severities as integers (0 debug … 4 fatal) or names.
+    module ExampleDebug
+      LOG_LEVEL_BY_NAME = {
+        "debug" => Logger::DEBUG,
+        "info" => Logger::INFO,
+        "warn" => Logger::WARN,
+        "error" => Logger::ERROR,
+        "fatal" => Logger::FATAL
+      }.freeze
+
+      module_function
+
+      def enabled?
+        truthy?(ENV["POLYRUN_EXAMPLE_DEBUG"])
+      end
+
+      def sql_enabled?
+        enabled? && (truthy?(ENV["POLYRUN_DEBUG_SQL"]) || truthy?(ENV["DEBUG_SQL"]))
+      end
+
+      def trace_enabled?
+        enabled? && (truthy?(ENV["POLYRUN_DEBUG_TRACE"]) || truthy?(ENV["DEBUG_TRACE"]))
+      end
+
+      def prosopite_enabled?
+        enabled? && truthy?(ENV["DEBUG_PROSOPITE"])
+      end
+
+      def print_spec_enabled?
+        enabled? && truthy?(ENV["DEBUG_PRINT_SPEC"])
+      end
+
+      def example_timeout_disabled?
+        enabled?
+      end
+
+      def log_level
+        parse_log_level(ENV.fetch("DEBUG_LOG_LEVEL", "debug"))
+      end
+
+      def rails_log_level
+        case log_level
+        when Logger::DEBUG then :debug
+        when Logger::INFO then :info
+        when Logger::WARN then :warn
+        when Logger::ERROR then :error
+        else :fatal
+        end
+      end
+
+      def parse_log_level(raw)
+        normalized = raw.to_s.strip.downcase
+        return LOG_LEVEL_BY_NAME.fetch(normalized) if LOG_LEVEL_BY_NAME.key?(normalized)
+
+        Integer(normalized)
+      rescue ArgumentError
+        Logger::DEBUG
+      end
+
+      def install!(rspec_config: fetch_rspec_configuration!)
+        install_spec_path_helpers!(rspec_config)
+        install_sql_debug!(rspec_config) if sql_enabled?
+        install_trace_debug!(rspec_config) if trace_enabled?
+      end
+
+      def install_rails_logging!(rspec_config: fetch_rspec_configuration!)
+        return unless enabled?
+        return unless defined?(Rails)
+
+        rspec_config.before do |example|
+          group = example.metadata[:example_group]
+          Polyrun::Log.puts "\n\nRunning #{group[:file_path]}:#{group[:line_number]}"
+
+          level = ExampleDebug.log_level
+          Rails.logger.level = level
+          if defined?(ActiveRecord::Base)
+            ar_logger = Logger.new(Polyrun::Log.stdout)
+            ar_logger.level = level
+            ActiveRecord::Base.logger = ar_logger
+          end
+        end
+      end
+
+      def install_example_timeout!(
+        rspec_config,
+        seconds: ENV.fetch("RSPEC_EXAMPLE_TIMEOUT_SEC", "30").to_f
+      )
+        return if seconds <= 0
+        return if example_timeout_disabled?
+
+        rspec_config.around(:each) do |example|
+          if example.metadata[:benchmark] || example.metadata[:slow]
+            example.run
+          else
+            Timeout.timeout(seconds) { example.run }
+          end
+        rescue Timeout::Error
+          raise "Example timed out after #{seconds}s (#{example.location})"
+        end
+      end
+
+      def install_prosopite!(rspec_config: fetch_rspec_configuration!)
+        return unless prosopite_enabled?
+        return unless defined?(Prosopite) && defined?(Rails)
+
+        log_path = Rails.root.join("tmp", "prosopite_#{Time.current.strftime("%Y%m%d_%H%M%S")}.log")
+        Prosopite.custom_logger = Logger.new(log_path)
+
+        rspec_config.before { Prosopite.scan }
+        rspec_config.after { Prosopite.finish }
+      end
+
+      def install_spec_path_helpers!(rspec_config)
+        rspec_config.before do |example|
+          group = example.metadata[:example_group]
+          spec_file_path = group[:file_path]
+
+          define_singleton_method(:spec_dirname) { File.dirname(spec_file_path) }
+          define_singleton_method(:spec_basename) { File.basename(spec_file_path) }
+
+          if ExampleDebug.print_spec_enabled?
+            Polyrun::Log.puts "\nRunning #{spec_file_path}:#{group[:line_number]}\n"
+          end
+        end
+
+        rspec_config.after do |example|
+          next unless ExampleDebug.print_spec_enabled?
+
+          group = example.metadata[:example_group]
+          Polyrun::Log.puts "\nFinished #{group[:file_path]}:#{group[:line_number]}\n"
+        end
+      end
+
+      def fetch_rspec_configuration!
+        require "rspec/core"
+        ::RSpec.configuration
+      end
+
+      def truthy?(value)
+        return false if value.nil?
+
+        %w[1 true yes on].include?(value.to_s.strip.downcase)
+      end
+      private_class_method :truthy?, :parse_log_level, :fetch_rspec_configuration!
+    end
+  end
+end

data/lib/polyrun/rspec/example_debug_instrumentation.rb

@@ -0,0 +1,73 @@
+module Polyrun
+  module RSpec
+    module ExampleDebug
+      SKIPPED_SQL_PREFIX = /\A(?:SELECT|SET|SHOW|BEGIN|COMMIT|ROLLBACK|RELEASE|SAVEPOINT)/
+
+      module_function
+
+      def install_sql_debug!(rspec_config, io: Polyrun::Log.stdout)
+        return unless defined?(ActiveSupport::Notifications)
+
+        rspec_config.around do |example|
+          subscriber = ActiveSupport::Notifications.subscribe("sql.active_record") do |event|
+            payload = event.payload[:sql]
+            next unless loggable_sql?(payload)
+
+            line = sql_with_interpolated_binds(payload, event.payload[:type_casted_binds])
+            io.puts "+ #{line}"
+          end
+
+          example.run
+        ensure
+          ActiveSupport::Notifications.unsubscribe(subscriber) if subscriber
+        end
+      end
+
+      def install_trace_debug!(rspec_config, root: trace_root, io: Polyrun::Log.stdout)
+        require "pp"
+        root_path = File.expand_path(root.to_s)
+        trace = TracePoint.new do |trace_point|
+          if trace_point.event == :call && trace_point.path.to_s.start_with?(root_path)
+            io.puts PP.pp({event: :call, path: "#{trace_point.path}:#{trace_point.lineno}"}, +"")
+          elsif trace_point.event == :raise
+            io.puts PP.pp(
+              {
+                event: :raise,
+                raised_exception: trace_point.raised_exception,
+                path: "#{trace_point.path}:#{trace_point.lineno}",
+                method_id: trace_point.method_id
+              },
+              +""
+            )
+          end
+        end
+
+        rspec_config.around do |example|
+          trace.enable
+          example.run
+        ensure
+          trace.disable
+        end
+      end
+
+      def loggable_sql?(sql)
+        !sql.to_s.match?(SKIPPED_SQL_PREFIX)
+      end
+
+      def sql_with_interpolated_binds(sql, binds)
+        output = sql.to_s.dup
+        Array(binds).each_with_index do |bind, index|
+          output = output.gsub("$#{index + 1}", "'#{bind}'")
+        end
+        output
+      end
+
+      def trace_root
+        return Rails.root.to_s if defined?(Rails)
+
+        Dir.pwd
+      end
+      private_class_method :trace_root
+    end
+  end
+end

data/lib/polyrun/rspec/sharded_formatter_compat.rb

@@ -0,0 +1,57 @@
+module Polyrun
+  module RSpec
+    # Formatter tweaks for progress formatters under +POLYRUN_SHARD_*+ workers.
+    module ShardedFormatterCompat
+      TextFormatterSilencer = Module.new do
+        def seed(_notification)
+        end
+
+        def dump_summary(_notification)
+        end
+
+        def dump_pending(_notification)
+        end
+      end
+
+      FuubarSeedSilencer = Module.new do
+        def seed(_notification)
+        end
+      end
+
+      module_function
+
+      def install!(rspec_config: fetch_rspec_configuration!)
+        return unless sharded_worker?
+
+        rspec_config.silence_filter_announcements = true
+        silence_text_formatter_noise!
+        silence_fuubar_seed! if defined?(Fuubar)
+      end
+
+      def sharded_worker?
+        !ENV["POLYRUN_SHARD_TOTAL"].to_s.strip.empty?
+      end
+
+      def silence_text_formatter_noise!
+        require "rspec/core/formatters/base_text_formatter"
+        klass = ::RSpec::Core::Formatters::BaseTextFormatter
+        return if klass.ancestors.include?(TextFormatterSilencer)
+
+        klass.prepend(TextFormatterSilencer)
+      end
+
+      def silence_fuubar_seed!
+        return unless defined?(Fuubar)
+        return if Fuubar.ancestors.include?(FuubarSeedSilencer)
+
+        Fuubar.prepend(FuubarSeedSilencer)
+      end
+
+      def fetch_rspec_configuration!
+        require "rspec/core"
+        ::RSpec.configuration
+      end
+      private_class_method :fetch_rspec_configuration!
+    end
+  end
+end

data/lib/polyrun/rspec.rb

@@ -72,5 +72,39 @@ module Polyrun
 
       Polyrun::WorkerPing.ensure_interval_ping_thread!
     end
+
+    def install_example_debug!(rspec_config: nil)
+      require_relative "rspec/example_debug"
+      Polyrun::RSpec::ExampleDebug.install!(rspec_config: rspec_config || fetch_rspec_configuration!)
+    end
+
+    def install_example_timeout!(rspec_config: nil, seconds: ENV.fetch("RSPEC_EXAMPLE_TIMEOUT_SEC", "30").to_f)
+      require_relative "rspec/example_debug"
+      Polyrun::RSpec::ExampleDebug.install_example_timeout!(
+        rspec_config || fetch_rspec_configuration!,
+        seconds: seconds
+      )
+    end
+
+    def install_example_rails_logging!(rspec_config: nil)
+      require_relative "rspec/example_debug"
+      Polyrun::RSpec::ExampleDebug.install_rails_logging!(rspec_config: rspec_config || fetch_rspec_configuration!)
+    end
+
+    def install_example_prosopite!(rspec_config: nil)
+      require_relative "rspec/example_debug"
+      Polyrun::RSpec::ExampleDebug.install_prosopite!(rspec_config: rspec_config || fetch_rspec_configuration!)
+    end
+
+    def install_sharded_formatter_compat!(rspec_config: nil)
+      require_relative "rspec/sharded_formatter_compat"
+      Polyrun::RSpec::ShardedFormatterCompat.install!(rspec_config: rspec_config || fetch_rspec_configuration!)
+    end
+
+    def fetch_rspec_configuration!
+      require "rspec/core"
+      ::RSpec.configuration
+    end
+    private_class_method :fetch_rspec_configuration!
   end
 end

data/lib/polyrun/spec_quality/profile.rb

@@ -4,18 +4,30 @@ module Polyrun
     module Profile
       module_function
 
-      def snapshot
-        cpu = Process.times
-        gc = GC.stat
-        io = read_proc_io
-        {
-          "cpu_user" => cpu.utime,
-          "cpu_system" => cpu.stime,
-          "gc_allocated" => gc[:total_allocated_objects],
-          "gc_heap_live" => gc[:heap_live_slots],
-          "io_read_bytes" => io[:read_bytes],
-          "io_write_bytes" => io[:write_bytes]
-        }
+      def snapshot(dimensions: %w[cpu mem io wall])
+        dims = enabled_dimensions(dimensions)
+        capture_all = dims.empty?
+        out = {}
+
+        if capture_all || dims.include?("cpu") || dims.include?("wall")
+          cpu = Process.times
+          out["cpu_user"] = cpu.utime
+          out["cpu_system"] = cpu.stime
+        end
+
+        if capture_all || dims.include?("mem")
+          gc = GC.stat
+          out["gc_allocated"] = gc[:total_allocated_objects]
+          out["gc_heap_live"] = gc[:heap_live_slots]
+        end
+
+        if capture_all || dims.include?("io")
+          io = read_proc_io
+          out["io_read_bytes"] = io[:read_bytes]
+          out["io_write_bytes"] = io[:write_bytes]
+        end
+
+        out
       end
 
       def diff(before, after)

data/lib/polyrun/spec_quality/report.rb

@@ -1,4 +1,7 @@
 # rubocop:disable Polyrun/FileLength, Metrics/ModuleLength -- report analysis + text formatting
+require_relative "../export/csv"
+require_relative "../export/markdown"
+
 module Polyrun
   module SpecQuality
     # Human-readable spec quality report from merged JSON.
@@ -55,6 +58,96 @@ module Polyrun
         lines.join("\n") + "\n"
       end
 
+      EXAMPLE_CSV_HEADERS = %w[example unique_lines line_churn max_line_churn shard_index].freeze
+
+      def format_csv(merged, cfg: {}, top: 30, profile: nil, plan_shards: nil)
+        rows = merged.fetch("examples", {}).map do |location, row|
+          [
+            location,
+            row["unique_lines"],
+            row["line_churn"],
+            row["max_line_churn"],
+            row["polyrun_shard_index"]
+          ]
+        end.sort_by { |row| [-row[2].to_i, row[0].to_s] }
+        rows = rows.first(top) if top
+        Export::Csv.generate(EXAMPLE_CSV_HEADERS, rows)
+      end
+
+      def format_markdown(merged, cfg: {}, top: 30, profile: nil, plan_shards: nil)
+        analysis = analyze(merged, cfg, plan_shards: plan_shards)
+        sections = markdown_sections(analysis, top).compact
+        Export::Markdown.document("Polyrun spec quality report", sections)
+      end
+
+      def markdown_sections(analysis, top)
+        [
+          markdown_shard_section(analysis[:shard_summary]),
+          markdown_zero_hit_section(analysis[:zero_hit], top),
+          markdown_hot_lines_section(analysis[:hot_lines], top),
+          markdown_churn_section(analysis[:line_churn], top)
+        ]
+      end
+
+      def markdown_shard_section(shard_summary)
+        shard_rows = (shard_summary || {}).sort_by { |shard, _| shard.to_s }.map do |shard, stats|
+          [shard, stats["examples"], stats["zero_hit"], stats["line_churn"]]
+        end
+        return if shard_rows.empty?
+
+        {
+          heading: "Shard attribution",
+          headers: %w[shard examples zero_hit line_churn],
+          rows: shard_rows
+        }
+      end
+
+      def markdown_zero_hit_section(zero_hit, top)
+        zero_rows = zero_hit.keys.sort.first(top).zip
+        {
+          heading: "Zero production lines",
+          headers: %w[example],
+          rows: zero_rows.empty? ? [["(none)"]] : zero_rows
+        }
+      end
+
+      def markdown_hot_lines_section(hot_lines, top)
+        hot_rows = hot_lines.first(top).map do |line, stats|
+          [line, stats["example_count"], stats["total_hits"]]
+        end
+        {
+          heading: "Hot lines",
+          headers: %w[line example_count total_hits],
+          rows: hot_rows.empty? ? [["(none)", 0, 0]] : hot_rows
+        }
+      end
+
+      def markdown_churn_section(churn_rows, top)
+        rows = churn_rows.first(top).map do |location, row|
+          [location, row["line_churn"], row["max_line_churn"]]
+        end
+        {
+          heading: "Per-example line churn",
+          headers: %w[example line_churn max_line_churn],
+          rows: rows.empty? ? [["(none)", 0, 0]] : rows
+        }
+      end
+
+      def render(merged, format: "text", **kwargs)
+        case format.to_s.downcase
+        when "text", "console", "txt"
+          format_report(merged, **kwargs)
+        when "json"
+          JSON.pretty_generate(analyze(merged, kwargs[:cfg] || {}, plan_shards: kwargs[:plan_shards]))
+        when "csv"
+          format_csv(merged, **kwargs)
+        when "markdown", "md"
+          format_markdown(merged, **kwargs)
+        else
+          raise Polyrun::Error, "report-spec-quality: unknown format #{format.inspect} (use text, json, csv, or markdown)"
+        end
+      end
+
       def gate_violations(merged, cfg = {})
         cfg = default_cfg(cfg)
         analysis = analyze(merged, cfg)

data/lib/polyrun/spec_quality.rb

@@ -58,8 +58,12 @@ module Polyrun
         @current = {
           location: normalize_location(location),
           wall_start: wall_start || Process.clock_gettime(Process::CLOCK_MONOTONIC),
-          coverage_before: Coverage::ExampleDiff.peek_blob,
-          profile_before: Profile.snapshot,
+          coverage_before: Coverage::ExampleDiff.peek_blob(
+            root: @config["root"],
+            track_under: @config["track_under"],
+            ignore_paths: @config["ignore_paths"]
+          ),
+          profile_before: Profile.snapshot(dimensions: @config["profile"]),
           sql_count: 0,
           sql_fingerprints: Hash.new(0),
           factory_counts: {}
@@ -78,16 +82,9 @@ module Polyrun
         loc = location || cur[:location]
         return if loc.nil? || loc.to_s.empty?
 
-        after_cov = Coverage::ExampleDiff.peek_blob
-        delta = Coverage::ExampleDiff.diff(cur[:coverage_before], after_cov)
-        delta = Coverage::ExampleDiff.apply_track_under(
-          delta,
-          root: @config["root"],
-          track_under: @config["track_under"],
-          ignore_paths: @config["ignore_paths"]
-        )
+        delta = coverage_delta_for_example(cur)
 
-        profile_after = Profile.snapshot
+        profile_after = Profile.snapshot(dimensions: @config["profile"])
         profile_delta = Profile.diff(cur[:profile_before], profile_after)
         wall = Process.clock_gettime(Process::CLOCK_MONOTONIC) - cur[:wall_start]
         profile_delta["wall"] = wall
@@ -169,6 +166,17 @@ module Polyrun
         Polyrun::Partition::TimingKeys.canonical_file_path(File.expand_path(s, root))
       end
 
+      def coverage_delta_for_example(cur)
+        after_source = Coverage::ExampleDiff.coverage_active? ? ::Coverage.peek_result : {}
+        Coverage::ExampleDiff.diff(
+          cur[:coverage_before],
+          after_source,
+          root: @config["root"],
+          track_under: @config["track_under"],
+          ignore_paths: @config["ignore_paths"]
+        )
+      end
+
       def build_row(cur, location, delta, profile_delta, factory_counts)
         profile = Profile.slice_profile(profile_delta, @config["profile"])
         repeated_sql = cur[:sql_fingerprints].select { |_sql, n| n >= min_query_count }.transform_keys(&:to_s)