polyrun 1.5.0 → 2.1.0

data/lib/polyrun/partition/timing_keys.rb

@@ -1,6 +1,7 @@
 require "json"
 
 require_relative "../log"
+require_relative "../timing/stats"
 
 module Polyrun
   module Partition
@@ -70,7 +71,7 @@ module Polyrun
         out = {}
         data.each do |k, v|
           key = normalize_locator(k.to_s, root, g)
-          fv = v.to_f
+          fv = Polyrun::Timing::Stats.binpack_weight(v)
           if out.key?(key) && out[key] != fv
             Polyrun::Log.warn(
               "polyrun: timing JSON duplicate key #{key.inspect} after normalize (#{out[key]} vs #{fv}); using #{fv}"

data/lib/polyrun/queue/duration.rb

@@ -0,0 +1,30 @@
+require "json"
+require "optparse"
+require "shellwords"
+
+module Polyrun
+  module Queue
+    # Parse duration strings like 10m, 1h, 600s into seconds.
+    module Duration
+      module_function
+
+      def parse_seconds(text)
+        s = text.to_s.strip
+        return Float(s) if s.match?(/\A\d+(\.\d+)?\z/)
+
+        m = s.match(/\A(\d+(?:\.\d+)?)(s|m|h|d)\z/i)
+        raise Polyrun::Error, "invalid duration: #{text.inspect}" unless m
+
+        val = Float(m[1])
+        case m[2].downcase
+        when "s" then val
+        when "m" then val * 60
+        when "h" then val * 3600
+        when "d" then val * 86_400
+        else
+          raise Polyrun::Error, "invalid duration: #{text.inspect}"
+        end
+      end
+    end
+  end
+end

data/lib/polyrun/queue/file_store.rb

@@ -1,3 +1,4 @@
+# rubocop:disable Polyrun/FileLength, Metrics/ClassLength -- file-backed queue chunks + leases
 require "fileutils"
 require "json"
 require "securerandom"
@@ -77,19 +78,121 @@ module Polyrun
         true
       end
 
-      def status
+      def status(detailed: false)
         with_lock do
           meta = load_meta!
-          {
+          leases = read_leases
+          base = {
             "pending" => Integer(meta["pending_count"]),
             "done" => Integer(meta["done_count"]),
-            "leases" => read_leases.keys.size
+            "leases" => leases.keys.size
           }
+          return base unless detailed
+
+          base.merge("lease_details" => lease_details(leases))
+        end
+      end
+
+      # Reclaim leases older than +older_than+ seconds and/or matching +worker_id+ when set.
+      # @return [Integer] number of paths returned to pending
+      def reclaim!(older_than: nil, worker_id: nil)
+        reclaimed_paths = 0
+        with_lock do
+          meta = load_meta!
+          leases = read_leases
+          keep = {}
+          leases.each do |lease_id, lease|
+            if reclaim_lease?(lease, older_than: older_than, worker_id: worker_id)
+              paths = lease["paths"] || []
+              return_paths_to_pending!(meta, paths)
+              reclaimed_paths += paths.size
+              append_ledger(
+                "RECLAIM" => lease_id,
+                "worker_id" => lease["worker_id"],
+                "paths" => paths
+              )
+            else
+              keep[lease_id] = lease
+            end
+          end
+          write_leases!(keep)
+          write_meta!(meta)
+        end
+        reclaimed_paths
+      end
+
+      def reclaim_lease!(lease_id)
+        reclaimed = 0
+        with_lock do
+          leases = read_leases
+          lease = leases[lease_id]
+          return 0 unless lease
+
+          leases.delete(lease_id)
+          write_leases!(leases)
+          meta = load_meta!
+          paths = lease["paths"] || []
+          return_paths_to_pending!(meta, paths)
+          write_meta!(meta)
+          reclaimed = paths.size
+          append_ledger("RECLAIM" => lease_id, "worker_id" => lease["worker_id"], "paths" => paths)
         end
+        reclaimed
       end
 
       private
 
+      def reclaim_lease?(lease, older_than:, worker_id:)
+        if worker_id && lease["worker_id"].to_s != worker_id.to_s
+          return false
+        end
+        if older_than
+          claimed = Time.parse(lease["claimed_at"].to_s)
+          return (Time.now - claimed) >= older_than
+        end
+        !!worker_id
+      rescue ArgumentError
+        true
+      end
+
+      def lease_details(leases)
+        now = Time.now
+        leases.map do |lease_id, lease|
+          claimed = Time.parse(lease["claimed_at"].to_s)
+          {
+            "lease_id" => lease_id,
+            "worker_id" => lease["worker_id"],
+            "paths_count" => (lease["paths"] || []).size,
+            "claimed_at" => lease["claimed_at"],
+            "age_seconds" => (now - claimed).round(1)
+          }
+        rescue ArgumentError
+          {
+            "lease_id" => lease_id,
+            "worker_id" => lease["worker_id"],
+            "paths_count" => (lease["paths"] || []).size,
+            "claimed_at" => lease["claimed_at"],
+            "age_seconds" => nil
+          }
+        end
+      end
+
+      def return_paths_to_pending!(meta, paths)
+        return if paths.empty?
+
+        meta["pending_count"] = Integer(meta["pending_count"]) + paths.size
+        files = sorted_chunk_files
+        if files.empty?
+          FileUtils.mkdir_p(pending_dir)
+          atomic_write(File.join(pending_dir, "000001.json"), JSON.generate(paths.map(&:to_s)))
+        else
+          head = files.first
+          chunk = JSON.parse(File.read(head))
+          chunk = paths.map(&:to_s) + chunk
+          atomic_write(head, JSON.generate(chunk))
+        end
+      end
+
       def queue_path
         File.join(@root, "queue.json")
       end
@@ -197,3 +300,4 @@ module Polyrun
 end
 
 require_relative "file_store_pending"
+# rubocop:enable Polyrun/FileLength, Metrics/ClassLength

data/lib/polyrun/quick/example_runner.rb

@@ -25,6 +25,7 @@ module Polyrun
         extend_capybara_if_enabled!
         qloc = quick_example_location(block)
         Polyrun::WorkerPing.ping!(location: qloc)
+        Polyrun::SpecQuality.start_example!(location: qloc) if Polyrun::SpecQuality.started?
         begin
           run_before_hooks_from_chain(ancestor_chain)
           instance_eval(&block)
@@ -34,6 +35,7 @@ module Polyrun
         rescue => e
           @reporter.error(group_name, description, e)
         ensure
+          Polyrun::SpecQuality.finish_example!(location: qloc) if Polyrun::SpecQuality.started?
           run_after_hooks_from_chain(ancestor_chain)
           reset_capybara_if_enabled!
           @_let_cache = {}

data/lib/polyrun/quick/runner.rb

@@ -1,3 +1,4 @@
+# rubocop:disable Polyrun/FileLength -- quick runner + spec quality wiring
 require "pathname"
 
 require_relative "assertions"
@@ -49,6 +50,14 @@ module Polyrun
         @capybara_enabled = false
       end
 
+      def install_spec_quality!(root: nil, output_path: nil)
+        require_relative "../spec_quality"
+        return unless Polyrun::SpecQuality.enabled?
+
+        r = root || File.expand_path(Dir.pwd)
+        Polyrun::SpecQuality.start!(root: r, output_path: output_path)
+      end
+
       def describe(name, &block)
         group = ExampleGroup.new(name)
         group.instance_eval(&block) if block
@@ -102,6 +111,7 @@ module Polyrun
         end
 
         quick_start_coverage_if_configured!
+        quick_start_spec_quality_if_configured!
 
         collector = load_quick_files!(files)
         return 1 unless collector
@@ -148,6 +158,16 @@ module Polyrun
         end
       end
 
+      def quick_start_spec_quality_if_configured!
+        return unless Polyrun::SpecQuality.spec_quality_requested_for_quick?(Dir.pwd)
+        return if Polyrun::SpecQuality.started?
+
+        require_relative "../spec_quality"
+        Polyrun::SpecQuality.start!(
+          root: File.expand_path(Dir.pwd)
+        )
+      end
+
       def quick_start_coverage_if_configured!
         return unless Polyrun::Coverage::Collector.coverage_requested_for_quick?(Dir.pwd)
         return if Polyrun::Coverage::Collector.started?
@@ -187,3 +207,4 @@ module Polyrun
     end
   end
 end
+# rubocop:enable Polyrun/FileLength

data/lib/polyrun/rspec.rb

@@ -47,6 +47,14 @@ module Polyrun
 
     # Writes {WorkerPing} after suite start, before/after each example (+location+ is file:line from metadata).
     # Keeps +--worker-idle-timeout+ sensitive to example progress (not only a background thread).
+    def install_spec_quality!(only_if: nil, root: nil, output_path: nil)
+      pred = only_if || -> { Polyrun::SpecQuality.enabled? }
+      return unless pred.call
+
+      require_relative "spec_quality/rspec_hook"
+      Polyrun::SpecQuality::RspecHook.install!(only_if: pred, root: root, output_path: output_path)
+    end
+
     def install_worker_ping!
       require "rspec/core"
       require_relative "worker_ping"

data/lib/polyrun/spec_quality/config.rb

@@ -0,0 +1,134 @@
+require "yaml"
+
+module Polyrun
+  module SpecQuality
+    # Loads +config/polyrun_spec_quality.yml+ and +ENV+ overrides.
+    module Config
+      DEFAULT_CONFIG_RELATIVE = File.join("config", "polyrun_spec_quality.yml").freeze
+
+      DEFAULTS = {
+        "track_under" => %w[lib app],
+        "min_line_churn" => 50,
+        "min_query_count" => 20,
+        "hot_line_example_overlap" => 10,
+        "strict" => false,
+        "sample" => 1.0,
+        "ignore_examples" => [],
+        "ignore_paths" => [],
+        "ignore_query_patterns" => [],
+        "profile" => %w[cpu mem],
+        "sql_counter" => false,
+        "minimum_unique_lines_per_example" => nil,
+        "max_zero_hit_examples" => nil,
+        "max_hot_line_overlap" => nil
+      }.freeze
+
+      module_function
+
+      def enabled?(env = ENV)
+        return false if disabled?(env)
+
+        truthy?(env["POLYRUN_SPEC_QUALITY"]) || truthy?(env["POLYRUN_SPEC_QUALITY_FRAGMENTS"])
+      end
+
+      def disabled?(env = ENV)
+        truthy?(env["POLYRUN_SPEC_QUALITY_DISABLE"])
+      end
+
+      def load(root:, config_path: nil, env: ENV, **overrides)
+        root = File.expand_path(root)
+        file_cfg = load_yaml(root, config_path)
+        merged = DEFAULTS.merge(stringify_keys(file_cfg))
+        apply_env!(merged, env)
+        merged.merge!(stringify_keys(overrides).transform_keys(&:to_s))
+        merged["root"] = root
+        merged["strict"] = resolve_strict(merged, env)
+        merged["sample"] = resolve_sample(merged, env)
+        normalize_config!(merged)
+        merged
+      end
+
+      def load_yaml(root, config_path)
+        path = config_path || File.join(root, DEFAULT_CONFIG_RELATIVE)
+        path = File.expand_path(path)
+        return {} unless File.file?(path)
+
+        data = YAML.load_file(path)
+        data.is_a?(Hash) ? data : {}
+      end
+
+      def apply_env!(cfg, env)
+        cfg["strict"] = true if truthy?(env["POLYRUN_SPEC_QUALITY_STRICT"])
+        if env.key?("POLYRUN_SPEC_QUALITY_SAMPLE")
+          cfg["sample"] = Float(env["POLYRUN_SPEC_QUALITY_SAMPLE"])
+        end
+        if env.key?("POLYRUN_SPEC_QUALITY_SQL_COUNTER")
+          cfg["sql_counter"] = truthy?(env["POLYRUN_SPEC_QUALITY_SQL_COUNTER"])
+        end
+        prof = env["POLYRUN_SPEC_QUALITY_PROFILE"]
+        cfg["profile"] = prof.split(",").map(&:strip).reject(&:empty?) if prof && !prof.strip.empty?
+      end
+
+      def resolve_strict(cfg, env)
+        return true if truthy?(env["POLYRUN_SPEC_QUALITY_STRICT"])
+
+        cfg["strict"] == true || truthy?(cfg["strict"])
+      end
+
+      def resolve_sample(cfg, env)
+        v = cfg["sample"]
+        f = v.is_a?(Numeric) ? v.to_f : Float(v)
+        f.clamp(0.0, 1.0)
+      rescue ArgumentError, TypeError
+        1.0
+      end
+
+      # rubocop:disable Metrics/AbcSize -- config key normalization
+      def normalize_config!(cfg)
+        cfg["track_under"] = Array(cfg["track_under"]).map(&:to_s).reject(&:empty?)
+        cfg["track_under"] = %w[lib] if cfg["track_under"].empty?
+        cfg["ignore_examples"] = Array(cfg["ignore_examples"]).map(&:to_s)
+        cfg["ignore_paths"] = Array(cfg["ignore_paths"]).map(&:to_s)
+        cfg["ignore_query_patterns"] = Array(cfg["ignore_query_patterns"]).map(&:to_s)
+        cfg["profile"] = Array(cfg["profile"]).map(&:to_s).reject(&:empty?)
+        %w[min_line_churn min_query_count hot_line_example_overlap].each do |k|
+          cfg[k] = Integer(cfg[k]) if cfg[k]
+        end
+      end
+      # rubocop:enable Metrics/AbcSize
+
+      def ignored_example?(location, ignore_examples)
+        loc = location.to_s
+        return false if loc.empty?
+
+        Array(ignore_examples).any? do |pat|
+          if pat.start_with?("/") && pat.end_with?("/") && pat.size > 2
+            loc.match?(Regexp.new(pat[1..-2]))
+          else
+            loc.include?(pat)
+          end
+        rescue RegexpError
+          loc.include?(pat)
+        end
+      end
+
+      def stringify_keys(obj)
+        case obj
+        when Hash
+          obj.each_with_object({}) { |(k, v), out| out[k.to_s] = stringify_keys(v) }
+        when Array
+          obj.map { |e| stringify_keys(e) }
+        else
+          obj
+        end
+      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?
+    end
+  end
+end

data/lib/polyrun/spec_quality/fragment.rb

@@ -0,0 +1,39 @@
+require "fileutils"
+
+require "json"
+
+module Polyrun
+  module SpecQuality
+    module Fragment
+      module_function
+
+      def default_fragment_path(env = ENV)
+        dir = env.fetch("POLYRUN_SPEC_QUALITY_FRAGMENT_DIR", default_fragment_dir)
+        base = Polyrun::Coverage::CollectorFragmentMeta.fragment_default_basename_from_env(env)
+        File.expand_path(File.join(dir, "polyrun-spec-quality-fragment-#{base}.jsonl"))
+      end
+
+      def default_fragment_dir
+        File.join(Dir.pwd, "coverage")
+      end
+
+      def glob_pattern(cwd = Dir.pwd)
+        File.join(cwd, "coverage", "polyrun-spec-quality-fragment-*.jsonl")
+      end
+
+      def ensure_fragment_dir!(path)
+        FileUtils.mkdir_p(File.dirname(path))
+      end
+
+      def truncate_fragment!(path)
+        ensure_fragment_dir!(path)
+        File.write(path, "")
+      end
+
+      def append_row!(path, row)
+        ensure_fragment_dir!(path)
+        File.open(path, "a") { |f| f.puts(JSON.generate(row)) }
+      end
+    end
+  end
+end

data/lib/polyrun/spec_quality/merge.rb

@@ -0,0 +1,78 @@
+require "json"
+
+module Polyrun
+  module SpecQuality
+    module Merge
+      module_function
+
+      def merge_files(paths)
+        examples = {}
+        paths.each do |path|
+          merge_file_into!(examples, path)
+        end
+        build_merged_payload(examples, paths.size)
+      end
+
+      def merge_file_into!(examples, path)
+        File.foreach(path) do |line|
+          line = line.strip
+          next if line.empty?
+
+          row = JSON.parse(line)
+          key = row["example"].to_s
+          next if key.empty?
+
+          examples[key] = row
+        end
+      end
+
+      def build_merged_payload(examples, fragment_count)
+        hot_lines = aggregate_hot_lines(examples)
+        {
+          "examples" => examples,
+          "hot_lines" => hot_lines,
+          "shard_summary" => shard_summary(examples),
+          "meta" => {
+            "polyrun_version" => Polyrun::VERSION,
+            "fragment_count" => fragment_count,
+            "example_count" => examples.size
+          }
+        }
+      end
+
+      def shard_summary(examples)
+        by_shard = Hash.new { |h, k| h[k] = {"examples" => 0, "zero_hit" => 0, "line_churn" => 0} }
+        examples.each do |_loc, row|
+          shard = row["polyrun_shard_index"]
+          shard = shard.nil? ? "?" : shard.to_s
+          by_shard[shard]["examples"] += 1
+          by_shard[shard]["zero_hit"] += 1 if row["unique_lines"].to_i.zero?
+          by_shard[shard]["line_churn"] += row["line_churn"].to_i
+        end
+        by_shard
+      end
+
+      def aggregate_hot_lines(examples)
+        by_line = Hash.new { |h, k| h[k] = {"examples" => [], "total_hits" => 0} }
+        examples.each do |example_loc, row|
+          Array(row["lines"]).each do |entry|
+            path, line_no, delta = entry
+            key = "#{path}:#{line_no}"
+            by_line[key]["examples"] << example_loc
+            by_line[key]["total_hits"] += delta.to_i
+          end
+        end
+        by_line.transform_values do |v|
+          v["example_count"] = v["examples"].uniq.size
+          v
+        end
+      end
+
+      def merge_and_write(paths, output_path)
+        merged = merge_files(paths)
+        File.write(output_path, JSON.pretty_generate(merged))
+        merged
+      end
+    end
+  end
+end

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