polyrun 1.5.0 → 2.1.2

data/lib/polyrun/partition/timing_diagnostics.rb

@@ -0,0 +1,139 @@
+require "set"
+
+module Polyrun
+  module Partition
+    # Stale / missing timing coverage before cost-based partition.
+    module TimingDiagnostics
+      SUSPICIOUS_BASENAME = /system|feature|integration|playwright|capybara/i
+
+      module_function
+
+      # @return [Hash] analysis result with :missing_files, :stale_entries, :coverage, etc.
+      # rubocop:disable Metrics/AbcSize -- timing coverage scan
+      def analyze(items:, costs:, timing_path:, root:, granularity: :file)
+        root = File.expand_path(root || Dir.pwd)
+        g = TimingKeys.normalize_granularity(granularity)
+        item_keys = items.map { |p| lookup_key(p, root, g) }
+        cost_keys = costs&.keys || []
+
+        if g == :example
+          item_keys_set = item_keys.to_set
+          cost_keys_set = cost_keys.to_set
+          cost_file_keys_set = cost_keys.map { |k| file_from_locator(k) }.uniq.to_set
+          known = item_keys.count do |ik|
+            cost_keys_set.include?(ik) || cost_file_keys_set.include?(file_from_locator(ik))
+          end
+          missing = item_keys.reject do |ik|
+            cost_keys_set.include?(ik) || cost_file_keys_set.include?(file_from_locator(ik))
+          end
+          stale = cost_keys.reject { |k| item_keys_set.include?(k) }
+        else
+          known = item_keys.count { |k| costs&.key?(k) }
+          missing = item_keys.reject { |k| costs&.key?(k) }
+          stale = cost_keys.reject { |k| item_keys.include?(k) }
+        end
+        total = item_keys.size
+
+        coverage = total.zero? ? 1.0 : known.to_f / total
+        default_weight = default_weight_for(costs)
+        suspicious = missing.select { |k| suspicious_path?(k) }
+
+        {
+          missing_files: missing,
+          stale_entries: stale,
+          coverage: coverage,
+          known_files: known,
+          total_files: total,
+          timing_file_age: timing_file_age(timing_path),
+          default_weight: default_weight,
+          suspicious_missing: suspicious
+        }
+      end
+      # rubocop:enable Metrics/AbcSize
+
+      # rubocop:disable Metrics/AbcSize -- stale/missing timing warnings
+      def emit_warnings!(analysis)
+        cov = analysis[:coverage]
+        if cov < 0.50
+          Polyrun::Log.warn "polyrun: timing coverage #{format_percent(cov)} — binpack quality low; run full timing capture first"
+        elsif cov < 0.80
+          Polyrun::Log.warn "polyrun: timing coverage #{format_percent(cov)} (< 80%)"
+        end
+
+        dw = analysis[:default_weight]
+        Polyrun::Log.warn "polyrun: default weight for missing files: #{format("%.4f", dw)}s (mean of known costs)"
+
+        if analysis[:timing_file_age]
+          Polyrun::Log.warn "polyrun: timing file age: #{analysis[:timing_file_age]}"
+        end
+
+        missing = analysis[:missing_files]
+        unless missing.empty?
+          Polyrun::Log.warn "polyrun: #{missing.size} file(s) without timing data"
+          missing.first(10).each { |p| Polyrun::Log.warn "  missing: #{p}" }
+          Polyrun::Log.warn "  ..." if missing.size > 10
+        end
+
+        stale = analysis[:stale_entries]
+        unless stale.empty?
+          Polyrun::Log.warn "polyrun: #{stale.size} timing entry(ies) for files not in suite"
+          stale.first(5).each { |p| Polyrun::Log.warn "  stale: #{p}" }
+          Polyrun::Log.warn "  ..." if stale.size > 5
+        end
+
+        suspicious = analysis[:suspicious_missing]
+        return if suspicious.empty?
+
+        Polyrun::Log.warn "polyrun: suspicious missing timing (#{suspicious.size} slow-path pattern(s)):"
+        suspicious.first(5).each { |p| Polyrun::Log.warn "  suspicious: #{p}" }
+      end
+      # rubocop:enable Metrics/AbcSize
+
+      def lookup_key(path, root, granularity)
+        TimingKeys.normalize_locator(path.to_s, root, granularity)
+      end
+
+      def file_from_locator(key)
+        s = key.to_s
+        m = s.match(/\A(.+):(\d+)\z/)
+        m ? m[1] : s
+      end
+
+      def suspicious_path?(key)
+        base = File.basename(file_from_locator(key))
+        base.match?(SUSPICIOUS_BASENAME)
+      end
+
+      def default_weight_for(costs)
+        vals = costs&.values || []
+        return 1.0 if vals.empty?
+
+        vals.sum / vals.size.to_f
+      end
+
+      def timing_file_age(timing_path)
+        return nil unless timing_path
+
+        abs = File.expand_path(timing_path.to_s, Dir.pwd)
+        return nil unless File.file?(abs)
+
+        age_sec = Time.now - File.mtime(abs)
+        format_age(age_sec)
+      end
+
+      def format_age(sec)
+        if sec < 3600
+          format("%.0fm ago", sec / 60.0)
+        elsif sec < 86_400
+          format("%.1fh ago", sec / 3600.0)
+        else
+          format("%.1fd ago", sec / 86_400.0)
+        end
+      end
+
+      def format_percent(ratio)
+        format("%.1f%%", ratio * 100.0)
+      end
+    end
+  end
+end

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"
@@ -5,6 +6,13 @@ require "time"
 module Polyrun
   module Queue
     # File-backed queue (spec_queue.md): +queue.json+, +pending/*.json+ chunks, +done.jsonl+, +leases.json+ (OS flock).
+    #
+    # Path lifecycle (lease transitions):
+    #   init!           → paths in pending chunks only
+    #   claim!          → pending −batch → active lease in leases.json
+    #   ack!            → lease removed; paths appended to done.jsonl
+    #   reclaim!        → stale or matching lease → paths returned to pending
+    #   reclaim_lease!  → one lease by id → paths returned to pending
     class FileStore
       CHUNK_SIZE = 500
 
@@ -77,19 +85,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 +307,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

@@ -21,6 +21,8 @@ module Polyrun
         if output_path
           op = output_path
           Class.new(Polyrun::Timing::RSpecExampleFormatter) do
+            ::RSpec::Core::Formatters.register self, :example_finished, :close
+
             define_method(:timing_output_path) { op }
           end
         else
@@ -47,6 +49,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