polyrun 2.1.2 → 2.2.0

data/lib/polyrun/cli/run_queue_command.rb

@@ -3,6 +3,7 @@ require "optparse"
 require "shellwords"
 
 require_relative "../queue/duration"
+require_relative "../queue/worker_loop"
 
 module Polyrun
   class CLI
@@ -83,44 +84,16 @@ module Polyrun
         workers.times do |i|
           wid = "worker-#{i}"
           pid = Process.fork do
-            run_queue_worker_loop(store: store, worker_id: wid, batch: batch, cmd: cmd, on_failure: on_failure)
+            result = Polyrun::Queue::WorkerLoop.run(
+              store: store, worker_id: wid, batch: batch, cmd: cmd, on_failure: on_failure
+            )
+            exit result[:exit_code]
           end
           pids << {pid: pid, worker_id: wid}
         end
         pids
       end
 
-      def run_queue_worker_loop(store:, worker_id:, batch:, cmd:, on_failure:)
-        batches_ok = 0
-        batches_fail = 0
-        loop do
-          claim = store.claim!(worker_id: worker_id, batch_size: batch)
-          paths = claim["paths"] || []
-          break if paths.empty?
-
-          code = run_queue_run_batch(cmd, paths)
-          if code == 0
-            store.ack!(lease_id: claim["lease_id"], worker_id: worker_id)
-            batches_ok += 1
-          elsif on_failure.to_s == "requeue"
-            store.reclaim_lease!(claim["lease_id"])
-            batches_fail += 1
-            exit 1
-          else
-            batches_fail += 1
-            exit code.zero? ? 1 : code
-          end
-        end
-        exit 0
-      rescue Polyrun::Error => e
-        Polyrun::Log.warn "polyrun run-queue worker #{worker_id}: #{e.message}"
-        exit 2
-      end
-
-      def run_queue_run_batch(cmd, paths)
-        system(*cmd, *paths) ? 0 : ($?.exitstatus || 1)
-      end
-
       def run_queue_wait_workers(pids, store:, on_failure:)
         ok = 0
         fail = 0

data/lib/polyrun/cli/run_shards_parallel_children.rb

@@ -1,5 +1,6 @@
 require "fileutils"
 
+require_relative "../worker_output"
 require_relative "run_shards_parallel_wait"
 
 module Polyrun
@@ -22,6 +23,7 @@ module Polyrun
         mt = ctx[:matrix_shard_total]
 
         pids = []
+        Polyrun::WorkerOutput.prepare_log_dir! if Polyrun::WorkerOutput.routing_enabled?
         workers.times do |shard|
           paths = plan.shard(shard)
           if paths.empty?
@@ -60,6 +62,9 @@ module Polyrun
           pids << {pid: pid, shard: shard, spawned_at: spawned_at, ping_path: ping_path}
           Polyrun::Debug.log("[parent pid=#{$$}] run-shards: Process.spawn shard=#{shard} child_pid=#{pid} spec_files=#{paths.size}")
           Polyrun::Log.warn "polyrun run-shards: started shard #{shard} pid=#{pid} (#{paths.size} file(s))" if parallel
+          if Polyrun::WorkerOutput.routing_enabled? && parallel
+            Polyrun::Log.warn "polyrun run-shards: shard #{shard} log → #{Polyrun::WorkerOutput.log_path_for(shard)}"
+          end
         end
         [pids, nil]
       end
@@ -81,6 +86,8 @@ module Polyrun
       end
 
       def run_shards_spawn_one_worker(child_env, cmd, paths, hook_cfg)
+        return Polyrun::WorkerOutput.spawn_worker(child_env, cmd, paths, hook_cfg) if Polyrun::WorkerOutput.routing_enabled?
+
         if hook_cfg.worker_hooks? && !Polyrun::Hooks.disabled?
           Process.spawn(child_env, "sh", "-c", hook_cfg.build_worker_shell_script(cmd, paths))
         else

data/lib/polyrun/cli/run_shards_parallel_wait.rb

@@ -111,6 +111,7 @@ module Polyrun
       end
 
       def run_shards_finalize_reaped_worker!(h, hook_cfg, workers, st, shard_results, after_hook_err)
+        Polyrun::WorkerOutput.finish_worker(h[:pid])
         exitstatus = st.exitstatus
         ok = st.success?
         Polyrun::Debug.log("[parent pid=#{$$}] run-shards: Process.wait child_pid=#{h[:pid]} shard=#{h[:shard]} exit=#{exitstatus} success=#{ok}")
@@ -218,6 +219,7 @@ module Polyrun
         _t, loc = run_shards_read_worker_ping_payload(h[:ping_path])
         ping_suffix = (loc && !loc.to_s.strip.empty?) ? "; last ping #{loc.to_s.strip}" : ""
         Polyrun::Log.orchestration_warn "polyrun run-shards: WORKER IDLE TIMEOUT after #{idle_sec}s since last per-example progress ping — shard #{h[:shard]} pid #{h[:pid]}#{ping_suffix}."
+        Polyrun::WorkerOutput.warn_shard_log(h[:shard])
         Polyrun::Log.warn "polyrun run-shards: idle shard file sample: #{sample}#{suffix}"
         Polyrun::Log.warn "polyrun run-shards: enable per-example worker progress pings in your test setup so idle timeouts reflect real work; exit #{WORKER_IDLE_TIMEOUT_EXIT_STATUS}."
       end
@@ -262,6 +264,7 @@ module Polyrun
             ""
           end
         Polyrun::Log.orchestration_warn "polyrun run-shards: WORKER TIMEOUT after #{timeout_sec}s (wall time since worker spawn) — shard #{h[:shard]} pid #{h[:pid]}."
+        Polyrun::WorkerOutput.warn_shard_log(h[:shard])
         Polyrun::Log.warn "polyrun run-shards: timeout shard includes: #{sample}#{suffix}"
         Polyrun::Log.warn "polyrun run-shards: override with --worker-timeout SEC or POLYRUN_WORKER_TIMEOUT_SEC; recorded exit #{WORKER_TIMEOUT_EXIT_STATUS} for this worker."
       end

data/lib/polyrun/cli/run_shards_plan_options.rb

@@ -63,7 +63,7 @@ module Polyrun
         opts.on("--merge-format LIST", String) { |v| st[:merge_format] = v }
         opts.on("--merge-failures", "After all workers exit, merge failure fragments from tmp/polyrun_failures (requires failure fragments in test setup)") { st[:merge_failures] = true }
         opts.on("--merge-failures-output PATH", String) { |v| st[:merge_failures_output] = v }
-        opts.on("--merge-failures-format VAL", "jsonl (default) or json") { |v| st[:merge_failures_format] = v }
+        opts.on("--merge-failures-format VAL", "jsonl (default), json, csv, or markdown") { |v| st[:merge_failures_format] = v }
         opts.on("--merge-spec-quality", "After workers exit, merge spec-quality fragments from coverage (enable spec-quality collection in test setup)") { st[:merge_spec_quality] = true }
         opts.on("--merge-spec-quality-output PATH", String) { |v| st[:merge_spec_quality_output] = v }
         opts.on("--no-report-spec-quality", "Skip printing spec-quality report after merge") { st[:report_spec_quality] = false }

data/lib/polyrun/cli/run_shards_run.rb

@@ -124,6 +124,7 @@ module Polyrun
 
       def run_shards_warn_interleaved(parallel, pid_count)
         return unless parallel && pid_count > 1
+        return if Polyrun::WorkerOutput.routing_enabled?
 
         Polyrun::Log.warn "polyrun run-shards: #{pid_count} children running; RSpec output below may be interleaved."
         Polyrun::Log.warn "polyrun run-shards: each worker prints its own summary line; the last \"N examples\" line is not a total across shards."

data/lib/polyrun/cli/run_shards_worker_interrupt.rb

@@ -1,3 +1,5 @@
+require_relative "../worker_output"
+
 module Polyrun
   class CLI
     # SIGINT/SIGTERM handling and non-blocking reap for parallel worker PIDs (used by run-shards / ci-shard fan-out).
@@ -7,12 +9,17 @@ module Polyrun
       def run_shards_log_interrupt_workers(pids, _ctx)
         parts = pids.map { |h| "shard=#{h[:shard]} pid=#{h[:pid]}" }
         Polyrun::Log.orchestration_warn "polyrun run-shards: SIGINT/SIGTERM while waiting on workers — stopping: #{parts.join(", ")}"
-        Polyrun::Log.warn "polyrun run-shards: search this log for each shard's started … pid= line and RSpec output; repeat SIGINT during cleanup escalates to SIGKILL"
+        if Polyrun::WorkerOutput.routing_enabled?
+          Polyrun::Log.warn "polyrun run-shards: per-shard worker logs under #{Polyrun::WorkerOutput.worker_log_directory_label}"
+        else
+          Polyrun::Log.warn "polyrun run-shards: search this log for each shard's started … pid= line and RSpec output; repeat SIGINT during cleanup escalates to SIGKILL"
+        end
       end
 
       # Best-effort worker teardown then exit. Does not return.
       def run_shards_shutdown_on_signal!(pids, code)
         run_shards_log_interrupt_workers(pids, nil)
+        Polyrun::WorkerOutput.shutdown_all!
         run_shards_terminate_children!(pids)
         exit(code)
       rescue Interrupt
@@ -23,6 +30,7 @@ module Polyrun
 
       # Send SIGTERM to each worker PID and wait so Ctrl+C / SIGTERM does not leave orphans.
       def run_shards_terminate_children!(pids)
+        Polyrun::WorkerOutput.shutdown_all!
         run_shards_signal_workers_term(pids)
         run_shards_reap_worker_pids_interruptible(pids.map { |h| h[:pid] })
       end

data/lib/polyrun/cli/spec_quality_commands.rb

@@ -43,10 +43,11 @@ module Polyrun
         config_path = nil
         strict = false
         json_out = false
+        report_format = nil
         plan_paths = []
 
         OptionParser.new do |opts|
-          opts.banner = "usage: polyrun report-spec-quality -i FILE [-o PATH] [--top N] [--profile LIST] [--strict] [--json]"
+          opts.banner = "usage: polyrun report-spec-quality -i FILE [-o PATH] [--top N] [--profile LIST] [--strict] [--format text|json|csv|markdown] [--json]"
           opts.on("-i", "--input PATH", "Merged polyrun-spec-quality.json") { |v| input = v }
           opts.on("-o", "--output PATH", "Write report to file instead of stdout") { |v| out_file = v }
           opts.on("--top N", Integer) { |v| top = v }
@@ -54,6 +55,7 @@ module Polyrun
           opts.on("-c", "--config PATH", "polyrun_spec_quality.yml path") { |v| config_path = v }
           opts.on("--plan PATH", "Partition plan JSON (repeatable; polyrun plan output per shard)") { |v| plan_paths << v }
           opts.on("--strict", "Exit 1 when gate thresholds fail") { strict = true }
+          opts.on("--format VAL", "text (default), json, csv, or markdown") { |v| report_format = v }
           opts.on("--json", "Write analysis JSON instead of text report") { json_out = true }
         end.parse!(argv)
         input ||= argv.first
@@ -67,13 +69,20 @@ module Polyrun
         cfg = load_spec_quality_config(config_path)
         strict = true if cfg["strict"] || strict
         plan_shards = Polyrun::SpecQuality::PlanLoader.load_shards(plan_paths)
-
-        text = if json_out
-          JSON.pretty_generate(Polyrun::SpecQuality::Report.analyze(merged, cfg, plan_shards: plan_shards))
-        else
-          Polyrun::SpecQuality::Report.format_report(
-            merged, cfg: cfg, top: top, profile: profile, plan_shards: plan_shards
+        resolved_format = report_format || (json_out ? "json" : "text")
+
+        begin
+          text = Polyrun::SpecQuality::Report.render(
+            merged,
+            format: resolved_format,
+            cfg: cfg,
+            top: top,
+            profile: profile,
+            plan_shards: plan_shards
           )
+        rescue Polyrun::Error => e
+          Polyrun::Log.warn e.message.to_s
+          return 2
         end
 
         if out_file

data/lib/polyrun/cli.rb

@@ -14,6 +14,7 @@ require_relative "cli/run_queue_command"
 require_relative "cli/queue_command"
 require_relative "cli/timing_command"
 require_relative "cli/spec_quality_commands"
+require_relative "cli/benchmark_commands"
 require_relative "cli/init_command"
 require_relative "cli/quick_command"
 require_relative "cli/ci_shard_run_parse"
@@ -32,7 +33,7 @@ module Polyrun
 
     # Keep in sync with +dispatch_cli_command_subcommands+ (+when+ branches). Used for implicit path routing.
     DISPATCH_SUBCOMMAND_NAMES = %w[
-      plan prepare merge-coverage merge-failures merge-spec-quality report-coverage report-junit report-timing report-spec-quality
+      plan prepare merge-coverage merge-failures merge-spec-quality report-coverage report-junit report-timing report-spec-quality report-benchmark bench
       env config merge-timing db:setup-template db:setup-shard db:clone-shards
       run-shards parallel-rspec start build-paths init queue run-queue quick hook
     ].freeze
@@ -55,6 +56,7 @@ module Polyrun
     include QueueCommand
     include TimingCommand
     include SpecQualityCommands
+    include BenchmarkCommands
     include InitCommand
     include QuickCommand
     include CiShardRunParse
@@ -120,6 +122,7 @@ module Polyrun
           config_path = argv.shift or break
         when "-v", "--verbose"
           @verbose = true
+          ENV["POLYRUN_VERBOSE"] = "1"
           argv.shift
         when "-h", "--help"
           print_help
@@ -170,6 +173,10 @@ module Polyrun
         cmd_merge_spec_quality(argv)
       when "report-spec-quality"
         cmd_report_spec_quality(argv)
+      when "report-benchmark"
+        cmd_report_benchmark(argv)
+      when "bench"
+        cmd_bench(argv)
       when "db:setup-template"
         cmd_db_setup_template(argv, config_path)
       when "db:setup-shard"

data/lib/polyrun/coverage/example_diff.rb

@@ -1,63 +1,124 @@
+require_relative "example_diff_track_filter"
+require_relative "example_diff_snapshot"
+
 module Polyrun
   module Coverage
     # Per-example line hit deltas from stdlib +Coverage.peek_result+ snapshots.
     module ExampleDiff
       module_function
 
-      # @return [Hash{String=>Hash}] path => +{"lines"=>[...]}+
-      def peek_blob
+      # @return [Hash{String=>Hash}] path => sparse line snapshot
+      def peek_blob(root: nil, track_under: nil, ignore_paths: nil)
         return {} unless coverage_active?
 
-        normalize_peek(::Coverage.peek_result)
+        snapshot_peek(
+          ::Coverage.peek_result,
+          root: root,
+          track_under: track_under,
+          ignore_paths: ignore_paths
+        )
       end
 
-      def coverage_active?
-        defined?(::Coverage) && ::Coverage.respond_to?(:running?) && ::Coverage.running?
-      end
+      # Frozen snapshot for storage between peeks (stdlib mutates line arrays in place).
+      def snapshot_peek(raw, root: nil, track_under: nil, ignore_paths: nil)
+        return {} if raw.nil? || raw.empty?
 
-      def normalize_peek(raw)
+        filter = track_filter_for(root: root, track_under: track_under, ignore_paths: ignore_paths)
         out = {}
-        raw.each do |path, cov|
-          next unless cov.is_a?(Hash)
+        raw.each do |path, coverage_entry|
+          next unless coverage_entry.is_a?(Hash)
+          next if filter && !filter.include_path?(path.to_s)
 
-          lines = cov[:lines] || cov["lines"]
+          lines = coverage_entry[:lines] || coverage_entry["lines"]
           next unless lines.is_a?(Array)
 
-          out[path.to_s] = {"lines" => lines.map { |x| x }}
+          out[path.to_s] = Snapshot.sparse_snapshot_lines(lines)
         end
         out
       end
 
-      # @return [Hash] +:unique_lines+, +:line_churn+, +:max_line_churn+, +:lines+ (compact triples)
-      # rubocop:disable Metrics/AbcSize -- per-file coverage delta walk
-      def diff(before_blob, after_blob)
+      # +after_source+ may be a normalized blob or a raw +Coverage.peek_result+ hash.
+      def diff(before_blob, after_source, root: nil, track_under: nil, ignore_paths: nil)
+        filter = track_filter_for(root: root, track_under: track_under, ignore_paths: ignore_paths)
+        if raw_peek_result?(after_source)
+          diff_against_peek(before_blob, after_source, filter: filter)
+        else
+          diff_blobs(before_blob, after_source, filter: filter)
+        end
+      end
+
+      def coverage_active?
+        defined?(::Coverage) && ::Coverage.respond_to?(:running?) && ::Coverage.running?
+      end
+
+      def diff_blobs(before_blob, after_blob, filter: nil)
         before_blob ||= {}
         after_blob ||= {}
-        files = before_blob.keys | after_blob.keys
+        paths = collect_diff_paths(before_blob, after_blob, filter: filter)
+        diff_paths(paths, before_blob, after_blob, raw_after: false)
+      end
+
+      def diff_against_peek(before_blob, after_raw, filter: nil)
+        before_blob ||= {}
+        after_raw ||= {}
+        paths = collect_diff_paths(before_blob, after_raw, filter: filter)
+        diff_paths(paths, before_blob, after_raw, raw_after: true)
+      end
+
+      def filter_lines(lines, root:, track_under:, ignore_paths: [])
+        filter = TrackFilter.new(root: root, track_under: track_under, ignore_paths: ignore_paths)
+        lines.select { |path, _line, _delta| filter.include_path?(path) }
+      end
+
+      def apply_track_under(delta, root:, track_under:, ignore_paths: [])
+        filtered = filter_lines(delta[:lines] || [], root: root, track_under: track_under, ignore_paths: ignore_paths)
+        unique = filtered.size
+        churn = filtered.sum { |(_path, _line, hit_delta)| hit_delta }
+        max_churn = filtered.map { |(_path, _line, hit_delta)| hit_delta }.max || 0
+        {
+          unique_lines: unique,
+          line_churn: churn,
+          max_line_churn: max_churn,
+          lines: filtered
+        }
+      end
+
+      def line_array(entry)
+        return [] unless entry.is_a?(Hash)
+        return [] if entry["sparse"]
 
+        arr = entry["lines"] || entry[:lines]
+        arr.is_a?(Array) ? arr : []
+      end
+
+      def raw_peek_result?(source)
+        return false unless source.is_a?(Hash)
+        return false if source.empty?
+
+        entry = source.values.first
+        entry.is_a?(Hash) && (entry.key?(:lines) || entry.key?(:branches))
+      end
+
+      def diff_paths(paths, before_blob, after_blob, raw_after:)
         line_entries = []
         unique = 0
         churn = 0
         max_churn = 0
 
-        files.each do |path|
-          b_lines = line_array(before_blob[path])
-          a_lines = line_array(after_blob[path])
-          max_len = [b_lines.size, a_lines.size].max
-
-          (0...max_len).each do |i|
-            b = b_lines[i]
-            a = a_lines[i]
-            next if a.nil? && b.nil?
+        paths.each do |path|
+          before_entry = before_blob[path]
+          after_lines =
+            if raw_after
+              lines_from_peek_entry(path, after_blob)
+            else
+              line_array(after_blob[path])
+            end
 
-            delta = (integer_hit(a) - integer_hit(b))
-            next unless delta.positive?
-
-            line_no = i + 1
-            line_entries << [path, line_no, delta]
+          accumulate_line_delta(before_entry, after_lines) do |delta, line_no|
             unique += 1
             churn += delta
             max_churn = delta if delta > max_churn
+            line_entries << [path, line_no, delta]
           end
         end
 
@@ -68,55 +129,61 @@ module Polyrun
           lines: line_entries
         }
       end
-      # rubocop:enable Metrics/AbcSize
-
-      def filter_lines(lines, root:, track_under:, ignore_paths: [])
-        root = File.expand_path(root)
-        prefixes = Array(track_under).map { |d| File.join(root, d.to_s) }
-        ignore = Array(ignore_paths).map(&:to_s).reject(&:empty?)
-
-        lines.select do |path, _line, _delta|
-          p = File.expand_path(path.to_s, root)
-          next false if ignore.any? { |pat| path_matches_ignore?(p, pat) }
 
-          prefixes.any? { |pre| p == pre || p.start_with?(pre + "/") }
+      def collect_diff_paths(before_blob, after_blob, filter: nil)
+        keys = before_blob.keys.dup
+        after_blob.each_key do |path|
+          string_path = path.to_s
+          keys << string_path unless keys.include?(string_path)
         end
-      end
+        return keys unless filter
 
-      def apply_track_under(delta, root:, track_under:, ignore_paths: [])
-        filtered = filter_lines(delta[:lines] || [], root: root, track_under: track_under, ignore_paths: ignore_paths)
-        unique = filtered.size
-        churn = filtered.sum { |(_p, _l, d)| d }
-        max_churn = filtered.map { |(_p, _l, d)| d }.max || 0
-        {
-          unique_lines: unique,
-          line_churn: churn,
-          max_line_churn: max_churn,
-          lines: filtered
-        }
+        keys.select { |path| filter.include_path?(path) }
       end
 
-      def path_matches_ignore?(path, pattern)
-        return path.include?(pattern) if pattern.is_a?(String) && !pattern.start_with?("/")
+      def accumulate_line_delta(before_entry, after_lines)
+        before_hits = Snapshot.hits_map(before_entry)
+        before_max = before_hits.empty? ? 0 : before_hits.keys.max + 1
+        max_len = [after_lines.size, before_max].max
 
-        path.match?(Regexp.new(pattern))
-      rescue RegexpError
-        path.include?(pattern.to_s)
+        (0...max_len).each do |index|
+          before_hit = before_hits[index]
+          after_hit = after_lines[index]
+          next if after_hit.nil? && before_hit.nil?
+
+          delta = integer_hit(after_hit) - integer_hit(before_hit)
+          next unless delta.positive?
+
+          yield(delta, index + 1)
+        end
       end
 
-      def line_array(entry)
+      def lines_from_peek_entry(path, after_raw)
+        entry = after_raw[path] || after_raw[path.to_s]
         return [] unless entry.is_a?(Hash)
 
-        arr = entry["lines"] || entry[:lines]
+        arr = entry[:lines] || entry["lines"]
         arr.is_a?(Array) ? arr : []
       end
 
+      def track_filter_for(root:, track_under:, ignore_paths:)
+        return nil if track_under.nil? && ignore_paths.nil?
+
+        TrackFilter.new(
+          root: root || Dir.pwd,
+          track_under: track_under,
+          ignore_paths: ignore_paths || []
+        )
+      end
+
       def integer_hit(value)
         return 0 if value.nil?
+        return 0 if value == "ignored"
 
         value.is_a?(Integer) ? value : value.to_i
       end
-      private_class_method :line_array, :integer_hit
+      private_class_method :diff_paths, :collect_diff_paths, :accumulate_line_delta,
+        :lines_from_peek_entry, :track_filter_for, :integer_hit, :raw_peek_result?
     end
   end
 end

data/lib/polyrun/coverage/example_diff_snapshot.rb

@@ -0,0 +1,44 @@
+module Polyrun
+  module Coverage
+    module ExampleDiff
+      # Sparse line-hit snapshots for per-example diff storage.
+      module Snapshot
+        module_function
+
+        def sparse_snapshot_lines(lines)
+          {"sparse" => true, "hits" => dense_hits_map(lines)}
+        end
+
+        def hits_map(entry)
+          return {} if entry.nil?
+
+          if entry.is_a?(Hash) && entry["sparse"]
+            entry["hits"] || {}
+          else
+            dense_hits_map(ExampleDiff.line_array(entry))
+          end
+        end
+
+        def dense_hits_map(lines)
+          hits = {}
+          lines.each_with_index do |value, index|
+            stored = snapshot_line_value(value)
+            hits[index] = stored unless stored.nil?
+          end
+          hits
+        end
+
+        def snapshot_line_value(value)
+          case value
+          when nil then nil
+          when "ignored" then "ignored"
+          when Integer then value
+          else
+            parsed = Integer(value, exception: false)
+            parsed.nil? ? value : parsed
+          end
+        end
+      end
+    end
+  end
+end

data/lib/polyrun/coverage/example_diff_track_filter.rb

@@ -0,0 +1,51 @@
+module Polyrun
+  module Coverage
+    module ExampleDiff
+      # Path inclusion for scoped snapshots and track-aware diffs.
+      class TrackFilter
+        def initialize(root:, track_under: nil, ignore_paths: [])
+          @root = root ? File.expand_path(root) : nil
+          @track_under = Array(track_under).map(&:to_s).reject(&:empty?)
+          @ignore = Array(ignore_paths).map(&:to_s).reject(&:empty?)
+          @prefixes =
+            if @root && !@track_under.empty?
+              @track_under.map { |directory| File.join(@root, directory) }
+            else
+              []
+            end
+        end
+
+        def include_path?(path)
+          absolute = absolute_path(path)
+          return false if ignored?(absolute)
+
+          return true if @prefixes.empty?
+
+          @prefixes.any? { |prefix| absolute == prefix || absolute.start_with?(prefix + "/") }
+        end
+
+        private
+
+        def absolute_path(path)
+          if @root
+            File.expand_path(path.to_s, @root)
+          else
+            File.expand_path(path.to_s)
+          end
+        end
+
+        def ignored?(absolute)
+          @ignore.any? { |pattern| path_matches_ignore?(absolute, pattern) }
+        end
+
+        def path_matches_ignore?(path, pattern)
+          return path.include?(pattern) if !pattern.start_with?("/")
+
+          path.match?(Regexp.new(pattern))
+        rescue RegexpError
+          path.include?(pattern)
+        end
+      end
+    end
+  end
+end

data/lib/polyrun/coverage/file_stats_report.rb

@@ -0,0 +1,36 @@
+require_relative "../export/csv"
+require_relative "../export/markdown"
+
+module Polyrun
+  module Coverage
+    # Per-file line coverage tables for CSV and Markdown exports.
+    module FileStatsReport
+      HEADERS = %w[path line_percent lines_covered lines_relevant].freeze
+
+      module_function
+
+      def file_rows(coverage_blob)
+        coverage_blob.map do |path, file_entry|
+          line_percent, lines_relevant, lines_covered = Merge.file_line_stats(file_entry)
+          [path, format("%.2f", line_percent), lines_covered, lines_relevant]
+        end.sort_by { |row| row[1].to_f }
+      end
+
+      def emit_csv(coverage_blob)
+        Export::Csv.generate(HEADERS, file_rows(coverage_blob))
+      end
+
+      def emit_markdown(coverage_blob, title: "Polyrun coverage report")
+        summary = Merge.console_summary(coverage_blob)
+        summary_line = Merge.format_console_summary(summary).strip
+        Export::Markdown.document(
+          title,
+          [
+            {body: summary_line},
+            {heading: "Per-file coverage", headers: HEADERS, rows: file_rows(coverage_blob)}
+          ]
+        )
+      end
+    end
+  end
+end