polyrun 1.0.0

data/lib/polyrun/coverage/cobertura_zero_lines.rb

@@ -0,0 +1,32 @@
+module Polyrun
+  module Coverage
+    # Lists Cobertura +line+ elements with +hits="0"+ (optional dev aid). Set +SHOW_ZERO_COVERAGE=1+ and run
+    # after Cobertura XML exists (e.g. after {Collector} with Cobertura formatter).
+    # Uses a small string scan (no REXML) so the gem stays stdlib-only everywhere REXML may be omitted.
+    module CoberturaZeroLines
+      module_function
+
+      def run(xml_path:, filename_prefix: "lib/")
+        return unless ENV["SHOW_ZERO_COVERAGE"] == "1"
+        return unless File.file?(xml_path)
+
+        uncovered = extract(File.read(xml_path), filename_prefix: filename_prefix)
+        uncovered.sort_by { |e| [e[:file], e[:line]] }.each do |line_info|
+          Polyrun::Log.puts "#{line_info[:file]}:#{line_info[:line]}"
+        end
+      end
+
+      def extract(xml_text, filename_prefix: "lib/")
+        uncovered = []
+        xml_text.scan(/<class[^>]+filename="([^"]+)"[^>]*>(.*?)<\/class>/m) do |filename, class_body|
+          next unless filename.start_with?(filename_prefix)
+
+          class_body.scan(/<line number="(\d+)" hits="(\d+)"/) do |num_s, hits_s|
+            uncovered << {file: filename, line: num_s.to_i} if hits_s.to_i == 0
+          end
+        end
+        uncovered
+      end
+    end
+  end
+end

data/lib/polyrun/coverage/collector.rb

@@ -0,0 +1,184 @@
+require "coverage"
+require "fileutils"
+require "json"
+
+require_relative "cobertura_zero_lines"
+require_relative "filter"
+require_relative "formatter"
+require_relative "merge"
+require_relative "result"
+require_relative "track_files"
+require_relative "../debug"
+
+module Polyrun
+  module Coverage
+    # Stdlib +Coverage+ → SimpleCov-compatible JSON for +merge-coverage+ / +report-coverage+.
+    # No SimpleCov gem. Enable with +POLYRUN_COVERAGE=1+ or call +start!+ from spec_helper.
+    #
+    # Disable with +POLYRUN_COVERAGE_DISABLE=1+ or +SIMPLECOV_DISABLE=1+ (migration alias).
+    #
+    # Branch coverage: set +POLYRUN_COVERAGE_BRANCHES=1+ so stdlib +Coverage.start+ records branches;
+    # +merge-coverage+ merges branch keys when present in fragments.
+    module Collector
+      module_function
+
+      # @param root [String] project root (absolute or relative)
+      # @param reject_patterns [Array<String>] path substrings to drop (like SimpleCov add_filter)
+      # @param output_path [String, nil] default coverage/polyrun-fragment-<shard>.json
+      # @param minimum_line_percent [Float, nil] exit 1 if below (when strict)
+      # @param strict [Boolean] whether to exit non-zero on threshold failure (default true when minimum set)
+      # @param track_under [Array<String>] when +track_files+ is nil, only keep coverage keys under these dirs relative to +root+. Default +["lib"]+.
+      # @param track_files [String, Array<String>, nil] glob(s) relative to +root+ (e.g. +"{lib,app}/**/*.rb"+). Adds never-loaded files with simulated lines, like SimpleCov +track_files+.
+      # @param groups [Hash{String=>String}] group name => glob relative to +root+ (SimpleCov +add_group+); JSON gets +lines.covered_percent+ per group and optional "Ungrouped".
+      # @param meta [Hash] extra keys under merged JSON meta
+      # @param formatter [Object, nil] Object responding to +format(result, output_dir:, basename:)+ like SimpleCov formatters (e.g. {Formatter.multi} or {Formatter::MultiFormatter})
+      # @param report_output_dir [String, nil] directory for +formatter+ outputs (default +coverage/+ under +root+)
+      # @param report_basename [String] file prefix for formatter outputs (default +polyrun-coverage+)
+      def start!(root:, reject_patterns: [], track_under: ["lib"], track_files: nil, groups: nil, output_path: nil, minimum_line_percent: nil, strict: nil, meta: {}, formatter: nil, report_output_dir: nil, report_basename: "polyrun-coverage")
+        return if disabled?
+
+        root = File.expand_path(root)
+        shard = ENV.fetch("POLYRUN_SHARD_INDEX", "0")
+        output_path ||= File.join(root, "coverage", "polyrun-fragment-#{shard}.json")
+        strict = if minimum_line_percent.nil?
+          false
+        else
+          strict.nil? || strict
+        end
+
+        @config = {
+          root: root,
+          track_under: Array(track_under).map(&:to_s),
+          track_files: track_files,
+          groups: normalize_groups(groups),
+          reject_patterns: reject_patterns,
+          output_path: output_path,
+          minimum_line_percent: minimum_line_percent,
+          strict: strict,
+          meta: meta,
+          formatter: formatter,
+          report_output_dir: report_output_dir,
+          report_basename: report_basename,
+          shard_total_at_start: ENV["POLYRUN_SHARD_TOTAL"].to_i
+        }
+
+        unless ::Coverage.running?
+          ::Coverage.start(lines: true, branches: branch_coverage_enabled?)
+        end
+        unless instance_variable_defined?(:@collector_finish_at_exit_registered)
+          @collector_finish_at_exit_registered = true
+          at_exit { finish }
+        end
+        nil
+      end
+
+      def branch_coverage_enabled?
+        %w[1 true yes].include?(ENV["POLYRUN_COVERAGE_BRANCHES"]&.downcase)
+      end
+
+      def disabled?
+        %w[1 true yes].include?(ENV["POLYRUN_COVERAGE_DISABLE"]&.downcase) ||
+          %w[1 true yes].include?(ENV["SIMPLECOV_DISABLE"]&.downcase)
+      end
+
+      # True after a successful {start!} in this process (stdlib +Coverage+ is active).
+      def self.started?
+        instance_variable_defined?(:@config) && @config
+      end
+
+      # Whether +polyrun quick+ should call {Rails.start!} before loading quick files: not disabled,
+      # and (+POLYRUN_COVERAGE=1+ or (+config/polyrun_coverage.yml+ exists and +POLYRUN_QUICK_COVERAGE=1+)).
+      def self.coverage_requested_for_quick?(root = Dir.pwd)
+        return false if disabled?
+        return true if %w[1 true yes].include?(ENV["POLYRUN_COVERAGE"]&.to_s&.downcase)
+
+        path = File.join(File.expand_path(root), "config", "polyrun_coverage.yml")
+        return false unless File.file?(path)
+
+        # Config file alone is for merge/report defaults; opt-in so test suites that only
+        # keep polyrun_coverage.yml for gates do not start Collector during `polyrun quick`.
+        %w[1 true yes].include?(ENV["POLYRUN_QUICK_COVERAGE"]&.to_s&.downcase)
+      end
+
+      # When +POLYRUN_SHARD_TOTAL+ > 1, each worker only writes the JSON fragment; merged reports
+      # (+merge-coverage+ / +report-coverage+) are authoritative. Set +POLYRUN_COVERAGE_WORKER_FORMATS=1+
+      # to force per-worker formatter output (debug only; duplicates work N times).
+      def run_formatter_per_worker?
+        return true if ENV["POLYRUN_COVERAGE_WORKER_FORMATS"] == "1"
+
+        ENV["POLYRUN_SHARD_TOTAL"].to_i <= 1
+      end
+
+      def self.finish_debug_time_label
+        if ENV["POLYRUN_SHARD_TOTAL"].to_i > 1
+          "worker pid=#{$$} shard=#{ENV.fetch("POLYRUN_SHARD_INDEX", "?")} Coverage::Collector.finish (write fragment)"
+        else
+          "Coverage::Collector.finish (write fragment)"
+        end
+      end
+
+      def build_meta(cfg)
+        m = (cfg[:meta] || {}).transform_keys(&:to_s)
+        m["polyrun_version"] = Polyrun::VERSION
+        m["timestamp"] ||= Time.now.to_i
+        m["command_name"] ||= "rspec"
+        m["polyrun_coverage_root"] = cfg[:root].to_s
+        if cfg[:groups]
+          m["polyrun_coverage_groups"] = cfg[:groups].transform_keys(&:to_s).transform_values(&:to_s)
+        end
+        if cfg[:track_files]
+          m["polyrun_track_files"] = cfg[:track_files]
+        end
+        m
+      end
+
+      # Normalizes stdlib Coverage.result to merge-compatible file entries (lines; branches when collected).
+      def result_to_blob(raw)
+        out = {}
+        raw.each do |path, cov|
+          next unless cov.is_a?(Hash)
+
+          lines = cov[:lines] || cov["lines"]
+          next unless lines.is_a?(Array)
+
+          entry = {"lines" => lines.map { |x| x }}
+          br = cov[:branches] || cov["branches"]
+          entry["branches"] = br if br
+          out[path.to_s] = entry
+        end
+        out
+      end
+
+      def normalize_blob_paths(blob, root)
+        root = File.expand_path(root)
+        blob.each_with_object({}) do |(path, entry), acc|
+          acc[File.expand_path(path.to_s, root)] = entry
+        end
+      end
+
+      def normalize_groups(groups)
+        return nil if groups.nil?
+
+        h = groups.is_a?(Hash) ? groups : {}
+        return nil if h.empty?
+
+        h.transform_keys(&:to_s).transform_values(&:to_s)
+      end
+
+      def keep_under_root(blob, root, track_under)
+        return blob if track_under.nil? || track_under.empty?
+
+        root = File.expand_path(root)
+        prefixes = track_under.map { |d| File.join(root, d) }
+        blob.each_with_object({}) do |(path, entry), acc|
+          p = path.to_s
+          next unless prefixes.any? { |pre| p == pre || p.start_with?(pre + "/") }
+
+          acc[path] = entry
+        end
+      end
+    end
+  end
+end
+
+require_relative "collector_finish"

data/lib/polyrun/coverage/collector_finish.rb

@@ -0,0 +1,95 @@
+require "fileutils"
+require "json"
+
+module Polyrun
+  module Coverage
+    module Collector
+      module_function
+
+      def finish
+        cfg = @config || return # rubocop:disable ThreadSafety/ClassInstanceVariable -- Collector stores @config from start! (same process)
+        Polyrun::Debug.log_worker_kv(
+          collector_finish: "start",
+          polyrun_shard_index: ENV["POLYRUN_SHARD_INDEX"],
+          polyrun_shard_total: ENV["POLYRUN_SHARD_TOTAL"],
+          output_path: cfg[:output_path]
+        )
+        Polyrun::Debug.time(Collector.finish_debug_time_label) do
+          blob = Collector.send(:prepare_finish_blob, cfg)
+          summary = Merge.console_summary(blob)
+          group_payload = cfg[:groups] ? TrackFiles.group_summaries(blob, cfg[:root], cfg[:groups]) : nil
+
+          Collector.send(:exit_if_below_minimum_line_percent, cfg, summary)
+
+          Collector.send(:write_finish_fragment!, cfg, blob, group_payload)
+          Collector.send(:run_finish_formatter!, cfg, blob, group_payload)
+          Polyrun::Log.warn Merge.format_console_summary(summary) if ENV["POLYRUN_COVERAGE_VERBOSE"]
+        end
+      end
+
+      def self.prepare_finish_blob(cfg)
+        raw = ::Coverage.result
+        blob = Collector.result_to_blob(raw)
+        blob = Collector.normalize_blob_paths(blob, cfg[:root])
+        blob = Collector.send(:track_blob_for_finish, cfg, blob)
+        Filter.reject_matching_paths(blob, cfg[:reject_patterns])
+      end
+      private_class_method :prepare_finish_blob
+
+      def self.track_blob_for_finish(cfg, blob)
+        sharded = ENV["POLYRUN_SHARD_TOTAL"].to_i > 1
+        if cfg[:track_files]
+          return Collector.keep_under_root(blob, cfg[:root], cfg[:track_under]) if sharded
+
+          TrackFiles.merge_untracked_into_blob(blob, cfg[:root], cfg[:track_files])
+        else
+          Collector.keep_under_root(blob, cfg[:root], cfg[:track_under])
+        end
+      end
+      private_class_method :track_blob_for_finish
+
+      def self.write_finish_fragment!(cfg, blob, group_payload)
+        FileUtils.mkdir_p(File.dirname(cfg[:output_path]))
+        payload = Merge.to_simplecov_json(blob, meta: Collector.build_meta(cfg), groups: group_payload)
+        File.write(cfg[:output_path], JSON.generate(payload))
+        Polyrun::Debug.log_worker("Collector.finish: wrote #{cfg[:output_path]} bytes=#{File.size(cfg[:output_path])}")
+      end
+      private_class_method :write_finish_fragment!
+
+      def self.run_finish_formatter!(cfg, blob, group_payload)
+        return unless cfg[:formatter]
+
+        if Collector.run_formatter_per_worker?
+          dir = cfg[:report_output_dir] || File.join(cfg[:root], "coverage")
+          base = cfg[:report_basename] || "polyrun-coverage"
+          result = Result.new(blob, meta: Collector.build_meta(cfg), groups: group_payload)
+          Polyrun::Debug.time("Collector formatter (per-shard reports)") do
+            cfg[:formatter].format(result, output_dir: dir, basename: base)
+            xml_path = File.join(dir, "#{base}.xml")
+            CoberturaZeroLines.run(xml_path: xml_path, filename_prefix: "lib/") if File.file?(xml_path)
+          end
+        else
+          shard_total = ENV.fetch("POLYRUN_SHARD_TOTAL", "nil")
+          Polyrun::Debug.log_worker(
+            "Collector.finish: skipping per-worker formatter (POLYRUN_SHARD_TOTAL=#{shard_total}); " \
+            "use merge-coverage / report-coverage for full LCOV/Cobertura/HTML"
+          )
+        end
+      end
+      private_class_method :run_finish_formatter!
+
+      def self.exit_if_below_minimum_line_percent(cfg, summary)
+        shard_total = (cfg[:shard_total_at_start] || ENV["POLYRUN_SHARD_TOTAL"]).to_i
+        return unless cfg[:minimum_line_percent] && shard_total <= 1
+
+        min = cfg[:minimum_line_percent].to_f
+        return if summary[:line_percent].round >= min.round
+
+        Polyrun::Log.warn Merge.format_console_summary(summary)
+        Polyrun::Log.warn "Polyrun coverage: #{summary[:line_percent].round(2)}% rounds below minimum #{min}%."
+        exit 1 if cfg[:strict]
+      end
+      private_class_method :exit_if_below_minimum_line_percent
+    end
+  end
+end

data/lib/polyrun/coverage/filter.rb

@@ -0,0 +1,22 @@
+module Polyrun
+  module Coverage
+    # Drop paths from a coverage blob when the path matches any reject pattern (substring).
+    # Mirrors SimpleCov +add_filter+ style paths (e.g. "/lib/generators/").
+    module Filter
+      module_function
+
+      def reject_matching_paths(blob, patterns)
+        return blob unless blob.is_a?(Hash)
+
+        pats = Array(patterns).map(&:to_s).reject(&:empty?)
+        return blob if pats.empty?
+
+        blob.each_with_object({}) do |(path, entry), acc|
+          next if pats.any? { |p| path.to_s.include?(p) }
+
+          acc[path] = entry
+        end
+      end
+    end
+  end
+end

data/lib/polyrun/coverage/formatter.rb

@@ -0,0 +1,115 @@
+require "fileutils"
+require "json"
+
+require_relative "merge"
+require_relative "result"
+
+module Polyrun
+  module Coverage
+    # Formatters matching SimpleCov: +#format(result)+ receives a {Result} (and optional +output_dir+/+basename+).
+    # Use {MultiFormatter} to run several outputs; {Formatter.multi} builds that from symbols.
+    module Formatter
+      module_function
+
+      def multi(*names, output_dir:, basename: "polyrun-coverage")
+        names = names.flatten.compact
+        raise ArgumentError, "formatter.multi: need at least one format" if names.empty?
+
+        formatters = names.map { |n| builtin(n).new(output_dir: output_dir, basename: basename) }
+        MultiFormatter.new(formatters)
+      end
+
+      def builtin(name)
+        case name.to_sym
+        when :json then JsonFormatter
+        when :lcov then LcovFormatter
+        when :cobertura then CoberturaFormatter
+        when :console then ConsoleFormatter
+        when :html then HtmlFormatter
+        else
+          raise ArgumentError, "unknown coverage format: #{name.inspect} (expected :json, :lcov, :cobertura, :console, :html)"
+        end
+      end
+
+      # Base: subclasses implement +#write_files(result, output_dir, basename)+ returning +{ key => path }+.
+      class Base
+        def initialize(output_dir: nil, basename: "polyrun-coverage")
+          @default_output_dir = output_dir
+          @default_basename = basename
+        end
+
+        def format(result, output_dir: @default_output_dir, basename: @default_basename)
+          od = output_dir
+          raise ArgumentError, "#{self.class}: output_dir is required" if od.nil? || od.to_s.empty?
+
+          bn = basename || "polyrun-coverage"
+          FileUtils.mkdir_p(od)
+          write_files(result, od.to_s, bn.to_s)
+        end
+
+        def write_files(_result, _output_dir, _basename)
+          raise NotImplementedError
+        end
+      end
+
+      # Runs each formatter in order; merges returned path hashes (later keys win on duplicate).
+      class MultiFormatter
+        def initialize(formatters)
+          @formatters = Array(formatters)
+        end
+
+        attr_reader :formatters
+
+        def format(result, **kwargs)
+          @formatters.each_with_object({}) do |f, acc|
+            acc.merge!(f.format(result, **kwargs))
+          end
+        end
+      end
+
+      class JsonFormatter < Base
+        def write_files(result, output_dir, basename)
+          path = File.join(output_dir, "#{basename}.json")
+          payload = Merge.to_simplecov_json(result.coverage_blob, meta: result.meta, groups: result.groups)
+          File.write(path, JSON.generate(payload))
+          {json: path}
+        end
+      end
+
+      class LcovFormatter < Base
+        def write_files(result, output_dir, basename)
+          path = File.join(output_dir, "#{basename}.lcov")
+          File.write(path, Merge.emit_lcov(result.coverage_blob))
+          {lcov: path}
+        end
+      end
+
+      class CoberturaFormatter < Base
+        def write_files(result, output_dir, basename)
+          path = File.join(output_dir, "#{basename}.xml")
+          root = result.meta && (result.meta["polyrun_coverage_root"] || result.meta[:polyrun_coverage_root])
+          File.write(path, Merge.emit_cobertura(result.coverage_blob, root: root))
+          {cobertura: path}
+        end
+      end
+
+      class ConsoleFormatter < Base
+        def write_files(result, output_dir, basename)
+          path = File.join(output_dir, "#{basename}-summary.txt")
+          summary = Merge.console_summary(result.coverage_blob)
+          File.write(path, Merge.format_console_summary(summary))
+          {console: path}
+        end
+      end
+
+      class HtmlFormatter < Base
+        def write_files(result, output_dir, basename)
+          path = File.join(output_dir, "#{basename}.html")
+          title = (result.meta && result.meta["title"]) || (result.meta && result.meta[:title]) || "Polyrun coverage"
+          File.write(path, Merge.emit_html(result.coverage_blob, title: title))
+          {html: path}
+        end
+      end
+    end
+  end
+end

data/lib/polyrun/coverage/merge/formatters.rb

@@ -0,0 +1,181 @@
+require "cgi"
+require "pathname"
+
+module Polyrun
+  module Coverage
+    module Merge
+      module_function
+
+      def to_simplecov_json(coverage_blob, meta: {}, groups: nil, strip_internal_meta: true)
+        m = meta.is_a?(Hash) ? meta : {}
+        meta_out = {}
+        m.each { |k, v| meta_out[k.to_s] = v }
+        if strip_internal_meta
+          INTERNAL_META_KEYS.each { |k| meta_out.delete(k) }
+        end
+        meta_out["simplecov_version"] ||= Polyrun::VERSION
+        g =
+          if groups.nil?
+            {}
+          else
+            stringify_keys_deep(groups)
+          end
+        {
+          "meta" => meta_out,
+          "coverage" => stringify_keys_deep(coverage_blob),
+          "groups" => g
+        }
+      end
+
+      def stringify_keys_deep(obj)
+        case obj
+        when Hash
+          obj.each_with_object({}) { |(k, v), h| h[k.to_s] = stringify_keys_deep(v) }
+        when Array
+          obj.map { |e| stringify_keys_deep(e) }
+        else
+          obj
+        end
+      end
+
+      def emit_lcov(coverage_blob)
+        lines = []
+        coverage_blob.each do |path, file|
+          phys = path.to_s
+          lines << "TN:polyrun"
+          lines << "SF:#{phys}"
+          line_arr = line_array_from_file_entry(file)
+          next unless line_arr.is_a?(Array)
+
+          line_arr.each_with_index do |hit, i|
+            next if hit.nil? || hit == "ignored"
+
+            n = hit.to_i
+            lines << "DA:#{i + 1},#{n}" if n >= 0
+          end
+          lines << "end_of_record"
+        end
+        lines.join("\n") + "\n"
+      end
+
+      # Cobertura XML (no extra gems). Root metrics match common consumers (spec3.md).
+      # When +root+ is set, +filename+ on each +class+ is relative to that directory (for tools that expect +lib/...+).
+      # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity -- linear XML assembly
+      def emit_cobertura(coverage_blob, root: nil)
+        lines_valid = 0
+        lines_covered = 0
+        coverage_blob.each_value do |file|
+          line_arr = line_array_from_file_entry(file)
+          next unless line_arr.is_a?(Array)
+
+          line_arr.each do |hit|
+            next if hit.nil? || hit == "ignored"
+
+            lines_valid += 1
+            lines_covered += 1 if hit.to_i > 0
+          end
+        end
+        line_rate = lines_valid.positive? ? (lines_covered.to_f / lines_valid) : 0.0
+        ts = Time.now.to_i
+
+        lines = []
+        lines << '<?xml version="1.0" encoding="UTF-8"?>'
+        lines << '<!DOCTYPE coverage SYSTEM "http://cobertura.sourceforge.net/xml/coverage-04.dtd">'
+        lines << %(<coverage line-rate="#{line_rate}" branch-rate="0" lines-covered="#{lines_covered}" lines-valid="#{lines_valid}" branches-covered="0" branches-valid="0" complexity="0" timestamp="#{ts}" version="1">)
+        lines << '<packages><package name="app"><classes>'
+        coverage_blob.each do |path, file|
+          line_arr = line_array_from_file_entry(file)
+          next unless line_arr.is_a?(Array)
+
+          fname = CGI.escapeHTML(cobertura_display_path(path, root)).gsub("'", "&#39;")
+          lines << %(<class name="#{fname}" filename="#{fname}"><lines>)
+          line_arr.each_with_index do |hit, i|
+            next if hit.nil? || hit == "ignored"
+
+            n = hit.to_i
+            lines << %(<line number="#{i + 1}" hits="#{n}"/>)
+          end
+          lines << "</lines></class>"
+        end
+        lines << "</classes></package></packages></coverage>\n"
+        lines.join
+      end
+      # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+
+      def cobertura_display_path(path, root)
+        p = path.to_s
+        return p if root.nil? || root.to_s.empty?
+
+        abs = File.expand_path(p)
+        r = File.expand_path(root.to_s)
+        Pathname.new(abs).relative_path_from(Pathname.new(r)).to_s
+      rescue ArgumentError
+        abs
+      end
+
+      # Aggregate stats for a SimpleCov-compatible coverage blob (lines arrays only).
+      def console_summary(coverage_blob)
+        files = 0
+        relevant = 0
+        covered = 0
+        coverage_blob.each_value do |file|
+          line_arr = line_array_from_file_entry(file)
+          next unless line_arr.is_a?(Array)
+
+          files += 1
+          line_arr.each do |h|
+            next if h.nil? || h == "ignored"
+
+            relevant += 1
+            covered += 1 if h.to_i > 0
+          end
+        end
+        pct = relevant.positive? ? (100.0 * covered / relevant) : 0.0
+        {
+          files: files,
+          lines_relevant: relevant,
+          lines_covered: covered,
+          line_percent: pct
+        }
+      end
+
+      def format_console_summary(summary)
+        s = summary.is_a?(Hash) ? summary : console_summary(summary)
+        format(
+          "Polyrun coverage summary: %.2f%% lines (%d / %d) across %d files\n",
+          s[:line_percent] || s["line_percent"],
+          s[:lines_covered] || s["lines_covered"],
+          s[:lines_relevant] || s["lines_relevant"],
+          s[:files] || s["files"]
+        )
+      end
+
+      # Per-file line stats for HTML and other formatters.
+      # Integer line counts for one file entry (for O(files x groups) group aggregation).
+      def line_counts(file_entry)
+        line_arr = line_array_from_file_entry(file_entry)
+        return {relevant: 0, covered: 0} unless line_arr.is_a?(Array)
+
+        relevant = 0
+        covered = 0
+        line_arr.each do |h|
+          next if h.nil? || h == "ignored"
+
+          relevant += 1
+          covered += 1 if h.to_i > 0
+        end
+        {relevant: relevant, covered: covered}
+      end
+
+      def file_line_stats(file)
+        c = line_counts(file)
+        rel = c[:relevant]
+        cov = c[:covered]
+        pct = rel.positive? ? (100.0 * cov / rel) : 0.0
+        [pct, rel, cov]
+      end
+    end
+  end
+end
+
+require_relative "formatters_html"

data/lib/polyrun/coverage/merge/formatters_html.rb

@@ -0,0 +1,55 @@
+require "cgi"
+
+module Polyrun
+  module Coverage
+    module Merge
+      module_function
+
+      # Minimal standalone HTML report (no extra gems), index listing similar to SimpleCov.
+      def emit_html(coverage_blob, title: "Polyrun coverage")
+        summary = console_summary(coverage_blob)
+        rows = []
+        coverage_blob.keys.sort.each do |path|
+          file = coverage_blob[path]
+          pct, rel, cov = file_line_stats(file)
+          esc = CGI.escapeHTML(path.to_s)
+          rows << "<tr><td class=\"path\">#{esc}</td><td class=\"pct\">#{format("%.2f", pct)}</td><td class=\"hits\">#{cov} / #{rel}</td></tr>"
+        end
+        esc_title = CGI.escapeHTML(title.to_s)
+        <<~HTML
+          <!DOCTYPE html>
+          <html lang="en">
+          <head>
+            <meta charset="utf-8"/>
+            <title>#{esc_title}</title>
+            <style>
+              body { font-family: system-ui, sans-serif; margin: 1.5rem; color: #1a1a1a; }
+              h1 { font-size: 1.25rem; }
+              .summary { margin: 1rem 0; }
+              table { border-collapse: collapse; width: 100%; max-width: 56rem; }
+              th, td { border: 1px solid #ccc; padding: 0.35rem 0.5rem; text-align: left; }
+              th { background: #f4f4f4; }
+              tr:nth-child(even) { background: #fafafa; }
+              td.path { word-break: break-all; font-size: 0.9rem; }
+              td.pct { white-space: nowrap; }
+            </style>
+          </head>
+          <body>
+            <h1>#{esc_title}</h1>
+            <p class="summary">
+              <strong>#{format("%.2f", summary[:line_percent])}%</strong> lines
+              (#{summary[:lines_covered]} / #{summary[:lines_relevant]}) across #{summary[:files]} files
+            </p>
+            <table>
+              <thead><tr><th>File</th><th>Coverage</th><th>Lines (covered / relevant)</th></tr></thead>
+              <tbody>
+              #{rows.join("\n")}
+              </tbody>
+            </table>
+          </body>
+          </html>
+        HTML
+      end
+    end
+  end
+end