polyrun 1.5.0 → 2.1.2

data/lib/polyrun/spec_quality/minitest_hook.rb

@@ -0,0 +1,42 @@
+module Polyrun
+  module SpecQuality
+    # Minitest hook: per-test spec quality (requires minitest loaded).
+    module MinitestHook
+      module SpecQualityTestHook
+        def setup
+          Polyrun::SpecQuality.start_example!(location: polyrun_minitest_location)
+          super
+        end
+
+        def teardown
+          super
+          Polyrun::SpecQuality.finish_example!(location: polyrun_minitest_location)
+        end
+
+        private
+
+        def polyrun_minitest_location
+          file, line = method(name).source_location
+          (file && line) ? "#{file}:#{line}" : nil
+        rescue NameError
+          nil
+        end
+      end
+
+      module_function
+
+      def install!(only_if: nil, root: nil, output_path: nil)
+        pred = only_if || -> { Polyrun::SpecQuality.enabled? }
+        return unless pred.call
+
+        unless defined?(::Minitest::Test)
+          Polyrun::Log.warn "polyrun minitest: install_spec_quality! skipped (load minitest first)"
+          return
+        end
+
+        Polyrun::SpecQuality::RspecHook.ensure_started!(root: root, output_path: output_path)
+        ::Minitest::Test.send(:prepend, SpecQualityTestHook)
+      end
+    end
+  end
+end

data/lib/polyrun/spec_quality/plan_loader.rb

@@ -0,0 +1,47 @@
+require "json"
+
+module Polyrun
+  module SpecQuality
+    # Loads partition plan JSON for spec-quality ↔ shard correlation.
+    module PlanLoader
+      module_function
+
+      # @param paths [Array<String>] plan JSON files (+polyrun plan+ output per shard or a wrapper hash)
+      # @return [Hash{String=>Array<String>}] shard index string => spec file paths
+      def load_shards(paths)
+        out = {}
+        Array(paths).each do |path|
+          next unless File.file?(path)
+
+          data = JSON.parse(File.read(File.expand_path(path)))
+          merge_plan_data!(out, data)
+        end
+        out
+      end
+
+      def merge_plan_data!(out, data)
+        if data.is_a?(Hash) && data["shards"].is_a?(Hash)
+          data["shards"].each { |k, v| out[k.to_s] = Array(v).map(&:to_s) }
+          return
+        end
+
+        return unless data.is_a?(Hash)
+
+        shard = data["shard_index"]
+        paths = data["paths"]
+        return if shard.nil? || !paths.is_a?(Array)
+
+        out[shard.to_s] = paths.map(&:to_s)
+      end
+
+      # @return [String, nil] shard index for an example locator given plan shards
+      def shard_for_example(example_loc, plan_shards)
+        file = example_loc.to_s.sub(/:\d+\z/, "")
+        plan_shards.each do |shard, paths|
+          return shard if paths.any? { |p| file == p || file.end_with?("/#{File.basename(p)}") || file.include?(p) }
+        end
+        nil
+      end
+    end
+  end
+end

data/lib/polyrun/spec_quality/profile.rb

@@ -0,0 +1,91 @@
+module Polyrun
+  module SpecQuality
+    # Stdlib per-example CPU / allocation / IO snapshots.
+    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]
+        }
+      end
+
+      def diff(before, after)
+        before ||= {}
+        after ||= {}
+        out = {}
+        %w[cpu_user cpu_system gc_allocated gc_heap_live io_read_bytes io_write_bytes].each do |k|
+          b = before[k]
+          a = after[k]
+          next if b.nil? && a.nil?
+
+          delta = numeric(a) - numeric(b)
+          out[k] = delta if delta.positive? || k.start_with?("cpu")
+          out[k] = delta
+        end
+        out
+      end
+
+      def enabled_dimensions(profile_list)
+        Array(profile_list).map(&:to_s).map(&:downcase)
+      end
+
+      # rubocop:disable Metrics/AbcSize -- profile dimension slice
+      def slice_profile(diff, dimensions)
+        dims = enabled_dimensions(dimensions)
+        return diff if dims.empty?
+
+        out = {}
+        out["wall"] = diff["wall"] if diff.key?("wall") && dims.include?("wall")
+        if dims.include?("cpu")
+          out["cpu_user"] = diff["cpu_user"] if diff.key?("cpu_user")
+          out["cpu_system"] = diff["cpu_system"] if diff.key?("cpu_system")
+        end
+        if dims.include?("mem")
+          out["gc_allocated"] = diff["gc_allocated"] if diff.key?("gc_allocated")
+          out["gc_heap_live"] = diff["gc_heap_live"] if diff.key?("gc_heap_live")
+        end
+        if dims.include?("io")
+          out["io_read_bytes"] = diff["io_read_bytes"] if diff.key?("io_read_bytes")
+          out["io_write_bytes"] = diff["io_write_bytes"] if diff.key?("io_write_bytes")
+        end
+        out
+      end
+      # rubocop:enable Metrics/AbcSize
+
+      def read_proc_io
+        path = "/proc/self/io"
+        return {read_bytes: nil, write_bytes: nil} unless File.readable?(path)
+
+        read_bytes = nil
+        write_bytes = nil
+        File.foreach(path) do |line|
+          case line
+          when /\Aread_bytes:\s+(\d+)/
+            read_bytes = Regexp.last_match(1).to_i
+          when /\Awrite_bytes:\s+(\d+)/
+            write_bytes = Regexp.last_match(1).to_i
+          end
+        end
+        {read_bytes: read_bytes, write_bytes: write_bytes}
+      rescue SystemCallError
+        {read_bytes: nil, write_bytes: nil}
+      end
+
+      def numeric(value)
+        return 0 if value.nil?
+
+        value.is_a?(Numeric) ? value : value.to_f
+      end
+      private_class_method :numeric
+    end
+  end
+end

data/lib/polyrun/spec_quality/report.rb

@@ -0,0 +1,261 @@
+# rubocop:disable Polyrun/FileLength, Metrics/ModuleLength -- report analysis + text formatting
+module Polyrun
+  module SpecQuality
+    # Human-readable spec quality report from merged JSON.
+    module Report
+      module_function
+
+      # rubocop:disable Metrics/AbcSize -- merged example analysis
+      def analyze(merged, cfg = {}, plan_shards: nil)
+        cfg = default_cfg(cfg)
+        examples = merged["examples"] || {}
+        hot_lines = merged["hot_lines"] || {}
+        shard_summary = merged["shard_summary"] || Merge.shard_summary(examples)
+
+        zero_hit = examples.select { |_loc, row| row["unique_lines"].to_i.zero? }
+        churn = examples.select { |_loc, row| row["line_churn"].to_i >= cfg["min_line_churn"] }
+          .sort_by { |_loc, row| -row["line_churn"].to_i }
+        hot = hot_lines.select { |_line, h| h["example_count"].to_i >= cfg["hot_line_example_overlap"] }
+          .sort_by { |_line, h| [-h["example_count"].to_i, -h["total_hits"].to_i] }
+
+        outliers = build_outliers(examples, cfg)
+        partition_hints = partition_hints_for(hot, examples, plan_shards) if plan_shards && !plan_shards.empty?
+
+        {
+          zero_hit: zero_hit,
+          line_churn: churn,
+          hot_lines: hot,
+          outliers: outliers,
+          shard_summary: shard_summary,
+          partition_hints: partition_hints,
+          config: cfg
+        }
+      end
+      # rubocop:enable Metrics/AbcSize
+
+      def format_report(merged, cfg: {}, top: 30, profile: nil, plan_shards: nil)
+        analysis = analyze(merged, cfg, plan_shards: plan_shards)
+        lines = ["Polyrun spec quality report", ""]
+
+        lines.concat(format_shard_summary_section(analysis[:shard_summary]))
+        lines << ""
+        lines.concat(format_zero_hit_section(analysis[:zero_hit], top))
+        lines << ""
+        lines.concat(format_hot_lines_section(analysis[:hot_lines], top))
+        lines << ""
+        lines.concat(format_churn_section(analysis[:line_churn], top))
+        hints_section = format_partition_hints_section(analysis[:partition_hints], top)
+        unless hints_section.empty?
+          lines << ""
+          lines.concat(hints_section)
+        end
+        lines << ""
+        lines.concat(format_outliers_section(analysis[:outliers], top, profile))
+
+        lines.join("\n") + "\n"
+      end
+
+      def gate_violations(merged, cfg = {})
+        cfg = default_cfg(cfg)
+        analysis = analyze(merged, cfg)
+        violations = []
+
+        max_zero = cfg["max_zero_hit_examples"]
+        if max_zero && analysis[:zero_hit].size > max_zero.to_i
+          violations << "zero_hit_examples=#{analysis[:zero_hit].size} max=#{max_zero}"
+        end
+
+        min_unique = cfg["minimum_unique_lines_per_example"]
+        if min_unique
+          bad = analysis[:zero_hit].keys
+          if bad.size.positive?
+            violations << "examples_below_minimum_unique_lines=#{bad.size} minimum=#{min_unique}"
+          end
+        end
+
+        max_hot = cfg["max_hot_line_overlap"]
+        if max_hot
+          over = analysis[:hot_lines].count { |_k, h| h["example_count"].to_i > max_hot.to_i }
+          violations << "hot_line_overlap_count=#{over} max=#{max_hot}" if over.positive?
+        end
+
+        violations
+      end
+
+      def emit_warnings!(merged, cfg = {})
+        analyze(merged, cfg).fetch(:line_churn, {}).each do |loc, row|
+          Polyrun::Log.warn "polyrun spec-quality line_churn: #{loc} churn=#{row["line_churn"]}"
+        end
+      end
+
+      def default_cfg(cfg)
+        h = cfg.is_a?(Hash) ? cfg.transform_keys(&:to_s) : {}
+        SpecQuality::Config::DEFAULTS.merge(h)
+      end
+
+      def format_shard_summary_section(shard_summary)
+        lines = ["Shard attribution:"]
+        if shard_summary.nil? || shard_summary.empty?
+          lines << "  (none)"
+          return lines
+        end
+
+        shard_summary.sort_by { |k, _| k.to_s }.each do |shard, stats|
+          lines << format(
+            "  shard %s — examples=%d zero_hit=%d line_churn=%d",
+            shard,
+            stats["examples"],
+            stats["zero_hit"],
+            stats["line_churn"]
+          )
+        end
+        lines
+      end
+
+      def format_partition_hints_section(hints, top)
+        return [] if hints.nil? || hints.empty?
+
+        lines = ["Partition hints (hot lines × shard):"]
+        hints.first(top).each do |h|
+          lines << format("  %s — shard %s (%d examples)", h[:line], h[:shard], h[:example_count])
+        end
+        lines << "  …" if hints.size > top
+        lines
+      end
+
+      def partition_hints_for(hot_lines, examples, plan_shards)
+        hot_lines.filter_map do |line, h|
+          example_locs = h["examples"] || []
+          shard_counts = Hash.new(0)
+          example_locs.each do |loc|
+            s = PlanLoader.shard_for_example(loc, plan_shards) || examples.dig(loc, "polyrun_shard_index")&.to_s
+            shard_counts[s] += 1 if s
+          end
+          next if shard_counts.empty?
+
+          shard, count = shard_counts.max_by { |_s, n| n }
+          {line: line, shard: shard, example_count: count, total_hits: h["total_hits"]}
+        end.sort_by { |h| [-h[:example_count], -h[:total_hits]] }
+      end
+
+      def format_zero_hit_section(zero_hit, top)
+        lines = ["Zero production lines (#{zero_hit.size} examples):"]
+        if zero_hit.empty?
+          lines << "  (none)"
+          return lines
+        end
+
+        zero_hit.keys.sort.first(top).each { |loc| lines << "  #{loc}" }
+        lines << "  …" if zero_hit.size > top
+        lines
+      end
+
+      def format_hot_lines_section(hot_lines, top)
+        lines = ["Hot lines (shared across examples):"]
+        if hot_lines.empty?
+          lines << "  (none)"
+          return lines
+        end
+
+        hot_lines.first(top).each do |line, h|
+          lines << format("  %s — %d examples, %d cumulative hits", line, h["example_count"], h["total_hits"])
+        end
+        lines << "  …" if hot_lines.size > top
+        lines
+      end
+
+      def format_churn_section(churn_rows, top)
+        lines = ["Per-example line churn (top #{[top, churn_rows.size].min}):"]
+        if churn_rows.empty?
+          lines << "  (none)"
+          return lines
+        end
+
+        churn_rows.first(top).each do |loc, row|
+          lines << format("  %s — churn=%d max_line=%d", loc, row["line_churn"], row["max_line_churn"])
+        end
+        lines
+      end
+
+      # rubocop:disable Metrics/AbcSize -- outlier row filter
+      def build_outliers(examples, cfg)
+        examples.filter_map do |loc, row|
+          prof = row["profile"] || {}
+          unique = row["unique_lines"].to_i
+          wall = prof["wall"].to_f
+          alloc = prof["gc_allocated"].to_i
+          cpu = prof["cpu_user"].to_f + prof["cpu_system"].to_f
+          sql = row["sql_count"].to_i
+          factories = (row["factory_counts"] || {}).values.sum
+
+          score = 0
+          reasons = []
+          if unique.zero?
+            score += 10
+            reasons << "zero_lines"
+          end
+          if wall > 1.0 && unique < 3
+            score += 5
+            reasons << "slow_low_coverage"
+          end
+          if alloc > 50_000 && wall > 0.5
+            score += 3
+            reasons << "high_alloc"
+          end
+          if cpu > 0.5 && unique < 3
+            score += 3
+            reasons << "high_cpu_low_coverage"
+          end
+          if sql >= cfg["min_query_count"]
+            score += 4
+            reasons << "high_sql_count"
+          end
+          if factories >= 10
+            score += 2
+            reasons << "many_factories"
+          end
+          next if score.zero?
+
+          {location: loc, score: score, reasons: reasons, row: row}
+        end.sort_by { |h| -h[:score] }
+      end
+      # rubocop:enable Metrics/AbcSize
+
+      # rubocop:disable Metrics/AbcSize -- outlier text formatting
+      def format_outliers_section(outliers, top, profile)
+        lines = ["Correlated outliers (slow / empty / heavy):"]
+        if outliers.empty?
+          lines << "  (none)"
+          return lines
+        end
+
+        dims = profile ? profile.to_s.split(",").map(&:strip) : nil
+        outliers.first(top).each do |o|
+          row = o[:row]
+          prof = row["profile"] || {}
+          detail = o[:reasons].join(", ")
+          if dims.nil? || dims.empty?
+            lines << format("  %s — score=%d (%s)", o[:location], o[:score], detail)
+          else
+            prof_bits = dims.filter_map do |d|
+              case d
+              when "wall" then "wall=#{format("%.2f", prof["wall"])}" if prof["wall"]
+              when "cpu" then "cpu=#{format("%.2f", prof["cpu_user"].to_f + prof["cpu_system"].to_f)}"
+              when "mem" then "alloc=#{prof["gc_allocated"]}" if prof["gc_allocated"]
+              when "io"
+                r = prof["io_read_bytes"]
+                w = prof["io_write_bytes"]
+                "io=#{r}/#{w}" if r || w
+              end
+            end
+            lines << format("  %s — score=%d (%s) %s", o[:location], o[:score], detail, prof_bits.join(" "))
+          end
+        end
+        lines << "  …" if outliers.size > top
+        lines
+      end
+      # rubocop:enable Metrics/AbcSize
+    end
+  end
+end
+# rubocop:enable Polyrun/FileLength, Metrics/ModuleLength

data/lib/polyrun/spec_quality/rspec_hook.rb

@@ -0,0 +1,55 @@
+module Polyrun
+  module SpecQuality
+    # RSpec hooks for per-example spec quality recording.
+    module RspecHook
+      module_function
+
+      def install!(only_if: nil, root: nil, output_path: nil)
+        pred = only_if || -> { Polyrun::SpecQuality.enabled? }
+        return unless pred.call
+
+        require "rspec/core"
+        ensure_started!(root: root, output_path: output_path)
+
+        ::RSpec.configure do |config|
+          config.before(:each) do |example|
+            next if example.pending?
+
+            Polyrun::SpecQuality.start_example!(
+              location: example.metadata[:location] || example.location
+            )
+          end
+
+          config.after(:each) do |example|
+            Polyrun::SpecQuality.finish_example!(
+              location: example.metadata[:location] || example.location,
+              pending: example.pending?
+            )
+          end
+        end
+      end
+
+      def ensure_started!(root: nil, output_path: nil)
+        return if Polyrun::SpecQuality.started?
+
+        Polyrun::SpecQuality.start!(
+          root: root || infer_root,
+          output_path: output_path
+        )
+      end
+
+      def infer_root
+        if defined?(::Rails) && ::Rails.respond_to?(:root) && ::Rails.root
+          return ::Rails.root.to_s
+        end
+
+        caller_locations.each do |loc|
+          inferred = Polyrun::Coverage::Rails.infer_root_from_path(loc.path)
+          return inferred if inferred
+        end
+
+        Dir.pwd
+      end
+    end
+  end
+end

data/lib/polyrun/spec_quality/sql_counter.rb

@@ -0,0 +1,34 @@
+module Polyrun
+  module SpecQuality
+    # Optional per-example SQL query counting via ActiveSupport::Notifications.
+    module SqlCounter
+      class << self
+        def install!
+          return false unless notifications_available?
+          return true if @installed
+
+          @installed = true
+          @subscriber = ActiveSupport::Notifications.subscribe("sql.active_record") do |*args|
+            next unless Polyrun::SpecQuality.recording?
+
+            event = ActiveSupport::Notifications::Event.new(*args)
+            Polyrun::SpecQuality.record_sql!(event.payload[:sql].to_s)
+          end
+          true
+        end
+
+        def uninstall!
+          return unless @installed && @subscriber
+
+          ActiveSupport::Notifications.unsubscribe(@subscriber)
+          @subscriber = nil
+          @installed = false
+        end
+
+        def notifications_available?
+          defined?(ActiveSupport::Notifications)
+        end
+      end
+    end
+  end
+end