polyrun 1.0.0

data/lib/polyrun/coverage/merge.rb

@@ -0,0 +1,127 @@
+require "json"
+
+module Polyrun
+  module Coverage
+    # Merges SimpleCov-compatible coverage blobs (line arrays and optional branches).
+    # Intended to be replaced or accelerated by a native extension for large suites.
+    #
+    # Complexity: +merge_two+ is linear in the number of file keys in its operands. Shards are combined with
+    # +merge_blob_tree+ (pairwise rounds), so total work stays linear in the sum of blob sizes across shards
+    # (same asymptotic cost as a left fold; shallower call depth). Group recomputation after merge is
+    # O(files x groups) with one pass over files (+TrackFiles.group_summaries+).
+    module Merge
+      module_function
+
+      # Merged coverage blob only (same as +merge_fragments(paths)[:blob]+).
+      # Uses a balanced binary tree of +merge_two+ calls (depth O(log k) for k shards) so work stays
+      # linear in total key count across merges; +merge_two+ is associative.
+      def merge_files(paths)
+        merge_fragments(paths)[:blob]
+      end
+
+      # Returns +{ blob:, meta:, groups: }+ where +groups+ is recomputed from merged blob when fragments
+      # include +meta.polyrun_coverage_root+ and +meta.polyrun_coverage_groups+ (emitted by {Collector}).
+      # When +meta.polyrun_track_files+ is present (sharded runs defer per-shard untracked expansion),
+      # applies +TrackFiles.merge_untracked_into_blob+ once on the merged blob so totals match serial.
+      def merge_fragments(paths)
+        return {blob: {}, meta: {}, groups: nil} if paths.empty?
+
+        docs = paths.map { |p| JSON.parse(File.read(p)) }
+        blobs = docs.map { |d| extract_coverage_blob(d) }
+        merged_blob = merge_blob_tree(blobs)
+        merged_meta = merge_fragment_metas(docs)
+        merged_blob = apply_track_files_once_after_merge(merged_blob, merged_meta)
+        groups_payload = recompute_groups_from_meta(merged_blob, merged_meta)
+        {blob: merged_blob, meta: merged_meta, groups: groups_payload}
+      end
+
+      def apply_track_files_once_after_merge(blob, merged_meta)
+        return blob unless merged_meta.is_a?(Hash)
+
+        tf = merged_meta["polyrun_track_files"]
+        root = merged_meta["polyrun_coverage_root"]
+        return blob if tf.nil? || root.nil?
+
+        require_relative "track_files"
+        TrackFiles.merge_untracked_into_blob(blob, root, tf)
+      end
+
+      # Balanced reduction: same total +merge_two+ work as a left fold, shallower call stack.
+      def merge_blob_tree(blobs)
+        return {} if blobs.empty?
+        return blobs.first if blobs.size == 1
+
+        list = blobs.dup
+        while list.size > 1
+          nxt = []
+          i = 0
+          while i < list.size
+            if i + 1 < list.size
+              nxt << merge_two(list[i], list[i + 1])
+              i += 2
+            else
+              nxt << list[i]
+              i += 1
+            end
+          end
+          list = nxt
+        end
+        list.first
+      end
+
+      INTERNAL_META_KEYS = %w[polyrun_coverage_root polyrun_coverage_groups polyrun_track_files].freeze
+
+      def normalize_track_files_meta(tf)
+        case tf
+        when Array then tf.map(&:to_s).sort
+        else [tf.to_s]
+        end
+      end
+
+      def recompute_groups_from_meta(blob, merged_meta)
+        return nil unless merged_meta.is_a?(Hash)
+
+        r = merged_meta["polyrun_coverage_root"]
+        g = merged_meta["polyrun_coverage_groups"]
+        return nil if r.nil? || g.nil? || g.empty?
+
+        require_relative "track_files"
+        TrackFiles.group_summaries(blob, r, g)
+      end
+
+      def parse_file(path)
+        text = File.read(path)
+        data = JSON.parse(text)
+        extract_coverage_blob(data)
+      end
+
+      # Picks top-level export `coverage`, merges all suite entries (e.g. RSpec + Minitest),
+      # and combines both when present.
+      def extract_coverage_blob(data)
+        return {} unless data.is_a?(Hash)
+
+        top = data["coverage"]
+        nested = []
+        data.each do |k, v|
+          next if k == "coverage"
+          next unless v.is_a?(Hash) && v["coverage"].is_a?(Hash)
+
+          nested << v["coverage"]
+        end
+
+        if nested.empty?
+          return top if top.is_a?(Hash)
+
+          return {}
+        end
+
+        merged = nested.reduce { |acc, el| merge_two(acc, el) }
+        top.is_a?(Hash) ? merge_two(top, merged) : merged
+      end
+    end
+  end
+end
+
+require_relative "merge_merge_two"
+require_relative "merge_fragment_meta"
+require_relative "merge/formatters"

data/lib/polyrun/coverage/merge_fragment_meta.rb

@@ -0,0 +1,47 @@
+module Polyrun
+  module Coverage
+    module Merge
+      module_function
+
+      def merge_fragment_metas(docs)
+        metas = docs.map { |d| extract_doc_meta(d) }
+        base = metas.first.dup
+        roots = metas.map { |m| m["polyrun_coverage_root"] }.compact
+        grs = metas.map { |m| m["polyrun_coverage_groups"] }.compact
+        tfs = metas.map { |m| m["polyrun_track_files"] }.compact
+        merge_fragment_meta_warn_root!(roots)
+        merge_fragment_meta_warn_groups!(grs)
+        merge_fragment_meta_warn_track_files!(tfs)
+        root = roots.first
+        groups_cfg = grs.first
+        track_files_cfg = tfs.first
+        base["polyrun_coverage_root"] = root if root
+        base["polyrun_coverage_groups"] = groups_cfg if groups_cfg
+        base["polyrun_track_files"] = track_files_cfg if track_files_cfg
+        base
+      end
+
+      def extract_doc_meta(d)
+        (d.is_a?(Hash) && d["meta"].is_a?(Hash)) ? d["meta"].transform_keys(&:to_s) : {}
+      end
+
+      def merge_fragment_meta_warn_root!(roots)
+        return if roots.uniq.size <= 1
+
+        Polyrun::Log.warn "Polyrun merge-coverage: polyrun_coverage_root differs across fragments; using first."
+      end
+
+      def merge_fragment_meta_warn_groups!(grs)
+        return if grs.uniq.size <= 1
+
+        Polyrun::Log.warn "Polyrun merge-coverage: polyrun_coverage_groups differs across fragments; using first."
+      end
+
+      def merge_fragment_meta_warn_track_files!(tfs)
+        return if tfs.map { |tf| JSON.generate(normalize_track_files_meta(tf)) }.uniq.size <= 1
+
+        Polyrun::Log.warn "Polyrun merge-coverage: polyrun_track_files differs across fragments; using first."
+      end
+    end
+  end
+end

data/lib/polyrun/coverage/merge_merge_two.rb

@@ -0,0 +1,117 @@
+module Polyrun
+  module Coverage
+    module Merge
+      module_function
+
+      def merge_two(a, b)
+        keys = a.keys | b.keys
+        out = {}
+        keys.each do |path|
+          out[path] = merge_file_entry(a[path], b[path])
+        end
+        out
+      end
+
+      def normalize_file_entry(v)
+        return nil if v.nil?
+        return {"lines" => v} if v.is_a?(Array)
+
+        v
+      end
+
+      def line_array_from_file_entry(file)
+        h = normalize_file_entry(file)
+        return nil unless h.is_a?(Hash)
+
+        h["lines"] || h[:lines]
+      end
+
+      def merge_file_entry(x, y)
+        x = normalize_file_entry(x)
+        y = normalize_file_entry(y)
+        return y if x.nil?
+        return x if y.nil?
+
+        lines = merge_line_arrays(x["lines"] || x[:lines], y["lines"] || y[:lines])
+        entry = {"lines" => lines}
+        bx = x["branches"] || x[:branches]
+        by = y["branches"] || y[:branches]
+        br = merge_branch_arrays(bx, by)
+        entry["branches"] = br if br
+        entry
+      end
+
+      def merge_line_arrays(a, b)
+        a ||= []
+        b ||= []
+        na = a.size
+        nb = b.size
+        max_len = (na > nb) ? na : nb
+        out = Array.new(max_len)
+        i = 0
+        while i < max_len
+          out[i] = merge_line_hits(a[i], b[i])
+          i += 1
+        end
+        out
+      end
+
+      def merge_line_hits(x, y)
+        return y if x.nil?
+        return x if y.nil?
+        return "ignored" if x == "ignored" || y == "ignored"
+
+        xi = line_hit_to_i(x)
+        yi = line_hit_to_i(y)
+        return xi + yi if xi && yi
+
+        return yi if xi.nil? && yi
+        return xi if yi.nil? && xi
+
+        x
+      end
+
+      def line_hit_to_i(v)
+        case v
+        when Integer then v
+        when nil then nil
+        else
+          Integer(v, exception: false)
+        end
+      end
+
+      def merge_branch_arrays(a, b)
+        return nil if a.nil? && b.nil?
+        return (a || b).dup if a.nil? || b.nil?
+
+        index = {}
+        [a, b].each do |arr|
+          arr.each do |br|
+            k = branch_key(br)
+            existing = index[k]
+            index[k] =
+              if existing
+                merge_branch_entries(existing, br)
+              else
+                br.dup
+              end
+          end
+        end
+        index.values.sort_by { |br| branch_key(br) }
+      end
+
+      def branch_key(br)
+        h = br.is_a?(Hash) ? br : {}
+        [h["type"] || h[:type], h["start_line"] || h[:start_line], h["end_line"] || h[:end_line]]
+      end
+
+      def merge_branch_entries(x, y)
+        out = x.is_a?(Hash) ? x.dup : {}
+        xc = (x["coverage"] || x[:coverage]).to_i
+        yc = (y["coverage"] || y[:coverage]).to_i
+        out["coverage"] = xc + yc
+        out
+      end
+    end
+  end
+end

data/lib/polyrun/coverage/rails.rb

@@ -0,0 +1,128 @@
+require "yaml"
+
+require_relative "collector"
+require_relative "formatter"
+
+module Polyrun
+  module Coverage
+    # Rails integration entry point for {Collector.start!}: optional +config/polyrun_coverage.yml+ under the project
+    # root, root inference from +spec_helper.rb+ / +rails_helper.rb+ / +test_helper.rb+, and +report_formats+ for
+    # {Formatter.multi}. Call at the **top** of +spec/spec_helper.rb+ (before +require "rails"+) so stdlib
+    # +Coverage+ sees application code.
+    #
+    #   require "polyrun/coverage/rails"
+    #   Polyrun::Coverage::Rails.start!
+    #
+    module Rails
+      module_function
+
+      DEFAULT_CONFIG_RELATIVE = File.join("config", "polyrun_coverage.yml").freeze
+
+      # @param root [String, nil] project root (default: infer from caller, or +Rails.root+ when already loaded)
+      # @param config_path [String, nil] YAML path (default: +<root>/config/polyrun_coverage.yml+ if present)
+      # @param overrides [Hash] merged over YAML; keys match {Collector.start!} (+report_formats+ builds +formatter+)
+      def start!(root: nil, config_path: nil, **overrides)
+        return if Collector.disabled?
+
+        root = resolve_root(root)
+        root = File.expand_path(root)
+        cfg = load_config(root, config_path)
+        merged = deep_merge_hashes(cfg, stringify_keys(overrides))
+        merged["root"] = root
+
+        report_formats = merged.delete("report_formats")
+        unless merged.key?("formatter") || report_formats.nil?
+          merged["formatter"] = build_formatter(Array(report_formats), root, merged)
+        end
+
+        Collector.start!(**collector_kwargs(merged))
+      end
+
+      # Exposed for tests and custom loaders.
+      def infer_root_from_path(path)
+        case File.basename(path.to_s)
+        when "spec_helper.rb", "rails_helper.rb", "test_helper.rb"
+          File.expand_path("..", File.dirname(path))
+        end
+      end
+
+      def resolve_root(explicit)
+        return File.expand_path(explicit) if explicit
+
+        if defined?(::Rails) && ::Rails.respond_to?(:root) && ::Rails.root
+          return ::Rails.root.to_s
+        end
+
+        caller_locations.each do |loc|
+          inferred = infer_root_from_path(loc.path)
+          return inferred if inferred
+        end
+
+        raise ArgumentError,
+          "Polyrun::Coverage::Rails.start! could not infer project root; pass root: (e.g. Rails.root or File.expand_path('..', __dir__))"
+      end
+
+      def load_config(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) ? stringify_keys(data) : {}
+      end
+
+      def build_formatter(formats, root, merged)
+        return nil if formats.empty?
+
+        dir = merged["report_output_dir"] || File.join(root, "coverage")
+        dir = File.expand_path(dir.to_s, root)
+        base = (merged["report_basename"] || "polyrun-coverage").to_s
+        Formatter.multi(*formats.map { |x| x.to_s.to_sym }, output_dir: dir, basename: base)
+      end
+
+      def collector_kwargs(h)
+        root = File.expand_path(h.fetch("root"))
+        {
+          root: root,
+          reject_patterns: Array(h["reject_patterns"] || []),
+          track_under: h.key?("track_under") ? Array(h["track_under"]) : ["lib"],
+          track_files: h["track_files"],
+          groups: h["groups"],
+          output_path: h["output_path"],
+          minimum_line_percent: h["minimum_line_percent"],
+          strict: h["strict"],
+          meta: h["meta"].is_a?(Hash) ? h["meta"] : {},
+          formatter: h["formatter"],
+          report_output_dir: (h["report_output_dir"] ? File.expand_path(h["report_output_dir"].to_s, root) : nil),
+          report_basename: (h["report_basename"] || "polyrun-coverage").to_s
+        }
+      end
+
+      def stringify_keys(obj)
+        case obj
+        when Hash
+          obj.each_with_object({}) do |(k, v), out|
+            out[k.to_s] = stringify_keys(v)
+          end
+        when Array
+          obj.map { |e| stringify_keys(e) }
+        else
+          obj
+        end
+      end
+
+      def deep_merge_hashes(a, b)
+        a = a.is_a?(Hash) ? a.dup : {}
+        b.each do |k, v|
+          key = k.to_s
+          a[key] = if a[key].is_a?(Hash) && v.is_a?(Hash)
+            deep_merge_hashes(a[key], stringify_keys(v))
+          else
+            stringify_keys(v)
+          end
+        end
+        a
+      end
+    end
+  end
+end

data/lib/polyrun/coverage/reporting.rb

@@ -0,0 +1,41 @@
+require "json"
+
+require_relative "formatter"
+require_relative "merge"
+require_relative "result"
+
+module Polyrun
+  module Coverage
+    # Ready-to-use multi-format output (SimpleCov-compatible result blob), no extra gems.
+    # Pass +formatter:+ for multi-formatter composition ({Formatter::MultiFormatter}, custom classes).
+    module Reporting
+      DEFAULT_FORMATS = %w[json lcov cobertura console html].freeze
+
+      # Comma list for +merge-coverage+ / +run-shards --merge-coverage+ defaults (Codecov, Jenkins, HTML, etc.).
+      DEFAULT_MERGE_FORMAT_LIST = DEFAULT_FORMATS.join(",").freeze
+
+      # Writes selected formats under output_dir using basename as file prefix (e.g. polyrun-coverage.json).
+      # When +formatter+ is nil, builds {Formatter.multi} from +formats+ (symbols or strings).
+      def self.write(coverage_blob, output_dir:, basename: "polyrun-coverage", formats: DEFAULT_FORMATS, meta: {}, groups: nil, formatter: nil)
+        fmt = formatter || Formatter.multi(*Array(formats).map(&:to_sym), output_dir: output_dir, basename: basename)
+        result = Result.new(coverage_blob, meta: meta, groups: groups)
+        fmt.format(result, output_dir: output_dir, basename: basename)
+      end
+
+      # Load a merged or raw JSON file from disk and write all requested formats.
+      def self.write_from_json_file(json_path, **kwargs)
+        text = File.read(json_path)
+        data = JSON.parse(text)
+        blob = Merge.extract_coverage_blob(data)
+        meta = kwargs.delete(:meta) || data["meta"] || {}
+        groups =
+          if kwargs.key?(:groups)
+            kwargs.delete(:groups)
+          else
+            data["groups"]
+          end
+        write(blob, meta: meta, groups: groups, **kwargs)
+      end
+    end
+  end
+end

data/lib/polyrun/coverage/result.rb

@@ -0,0 +1,18 @@
+module Polyrun
+  module Coverage
+    # Payload passed to formatters (SimpleCov-compatible): merged line coverage plus JSON meta/groups.
+    class Result
+      attr_reader :coverage_blob, :meta, :groups
+
+      def initialize(coverage_blob, meta: {}, groups: nil)
+        @coverage_blob = coverage_blob
+        @meta = meta.is_a?(Hash) ? meta : {}
+        @groups = groups
+      end
+
+      def files
+        coverage_blob.keys
+      end
+    end
+  end
+end

data/lib/polyrun/coverage/track_files.rb

@@ -0,0 +1,141 @@
+require "pathname"
+
+require_relative "merge"
+
+module Polyrun
+  module Coverage
+    # SimpleCov-compatible +track_files+ (globs from project root) and +add_group+ statistics
+    # for the JSON payload (+groups+ with +lines.covered_percent+ per group).
+    module TrackFiles
+      module_function
+
+      # Expands one or more glob patterns relative to +root+ (supports +{a,b}/**/*.rb+ with File::FNM_EXTGLOB).
+      def expand_globs(root, track_files)
+        root = File.expand_path(root)
+        patterns = Array(track_files).map(&:to_s).reject(&:empty?)
+        return [] if patterns.empty?
+
+        patterns.flat_map do |pattern|
+          Dir.chdir(root) do
+            Dir.glob(pattern, File::FNM_EXTGLOB)
+          end
+        end.map { |rel| File.expand_path(rel, root) }.uniq
+      end
+
+      # Adds tracked files that were never required, with simulated line arrays (blank/comment => nil, else 0).
+      # Matches SimpleCov +add_not_loaded_files+ behavior for coverage completeness.
+      def merge_untracked_into_blob(blob, root, track_files)
+        root = File.expand_path(root)
+        out = {}
+        blob.each do |k, v|
+          out[File.expand_path(k.to_s)] = v
+        end
+
+        expand_globs(root, track_files).each do |abs|
+          next if out.key?(abs)
+          next unless File.file?(abs)
+
+          out[abs] = {"lines" => simulated_lines_for_unloaded(abs)}
+        end
+        out
+      end
+
+      def simulated_lines_for_unloaded(path)
+        lines = []
+        File.foreach(path) do |line|
+          lines << (blank_or_comment?(line) ? nil : 0)
+        end
+        lines
+      rescue Errno::ENOENT, Errno::EACCES
+        []
+      end
+
+      def blank_or_comment?(line)
+        s = line.strip
+        s.empty? || s.start_with?("#")
+      end
+
+      # +groups+ is a Hash of group_name => glob pattern (relative to +root+), SimpleCov +add_group+ style.
+      # Produces the +groups+ section of SimpleCov JSON: each group has lines.covered_percent.
+      # Assignment uses paths present in +blob+ matching each glob (+File.fnmatch?+), not a fresh Dir.glob,
+      # so in-memory coverage lines up with reported files. Files matching no group get "Ungrouped".
+      def group_summaries(blob, root, groups)
+        return {} if groups.nil? || groups.empty?
+
+        root = File.expand_path(root)
+        normalized = {}
+        blob.each { |k, v| normalized[File.expand_path(k.to_s)] = v }
+
+        accum, ungrouped, any_ungrouped = group_summaries_accumulate(normalized, root, groups)
+        group_summaries_build_payload(groups, accum, ungrouped, any_ungrouped)
+      end
+
+      def group_summaries_accumulate(normalized, root, groups)
+        accum = Hash.new { |h, k| h[k] = {relevant: 0, covered: 0} }
+        ungrouped = {relevant: 0, covered: 0}
+        any_ungrouped_file = false
+
+        normalized.each do |abs, entry|
+          counts = Merge.line_counts(entry)
+          matched = []
+          groups.each do |name, glob_pattern|
+            matched << name.to_s if file_matches_glob?(abs, glob_pattern, root)
+          end
+          if matched.empty?
+            any_ungrouped_file = true
+            ungrouped[:relevant] += counts[:relevant]
+            ungrouped[:covered] += counts[:covered]
+          else
+            matched.each { |n| add_counts!(accum[n], counts) }
+          end
+        end
+        [accum, ungrouped, any_ungrouped_file]
+      end
+
+      def group_summaries_build_payload(groups, accum, ungrouped, any_ungrouped_file)
+        out = {}
+        groups.each_key do |name|
+          n = name.to_s
+          a = accum[n]
+          out[n] = {
+            "lines" => {
+              "covered_percent" => percent_from_counts(a[:relevant], a[:covered])
+            }
+          }
+        end
+
+        if any_ungrouped_file
+          out["Ungrouped"] = {
+            "lines" => {
+              "covered_percent" => percent_from_counts(ungrouped[:relevant], ungrouped[:covered])
+            }
+          }
+        end
+
+        out
+      end
+
+      def add_counts!(acc, delta)
+        acc[:relevant] += delta[:relevant]
+        acc[:covered] += delta[:covered]
+      end
+
+      def percent_from_counts(relevant, covered)
+        return round_percent(0.0) if relevant <= 0
+
+        round_percent(100.0 * covered / relevant)
+      end
+
+      def file_matches_glob?(absolute_path, pattern, root)
+        rel = Pathname.new(absolute_path).relative_path_from(Pathname.new(root)).to_s
+        File.fnmatch?(pattern, rel, File::FNM_PATHNAME | File::FNM_EXTGLOB)
+      rescue ArgumentError
+        File.fnmatch?(pattern, absolute_path, File::FNM_PATHNAME | File::FNM_EXTGLOB)
+      end
+
+      def round_percent(x)
+        x.to_f.round(2)
+      end
+    end
+  end
+end