polyrun 2.1.3 → 2.2.0

data/lib/polyrun/benchmark/profile.rb

@@ -0,0 +1,191 @@
+require "fileutils"
+require "json"
+require "open3"
+
+module Polyrun
+  module Benchmark
+    # Records benchmark output during performance specs and writes profile artifacts.
+    # Set POLYRUN_BENCH=1 to echo lines to stdout. JSON sidecar enables report-benchmark exports.
+    module Profile
+      module_function
+
+      def reset!
+        lines_storage.clear
+        metrics_storage.clear
+        current_section_storage.replace(["default"])
+      end
+
+      def log(message = "")
+        line = message.to_s
+        lines_storage << line
+        section = detect_section_title(line) || current_section_storage.first
+        current_section_storage[0] = section if detect_section_title(line)
+        $stdout.puts(line) if verbose? && !line.empty?
+        line
+      end
+
+      def record_metric!(name:, value:, unit: "seconds", section: nil)
+        section_name = section || current_section_storage.first
+        metric = {
+          "section" => section_name.to_s,
+          "name" => name.to_s,
+          "value" => value,
+          "unit" => unit.to_s
+        }
+        metrics_storage << metric
+        log(format_metric_line(metric))
+        metric
+      end
+
+      def snapshot
+        {
+          "meta" => profile_meta,
+          "lines" => lines_storage.dup,
+          "metrics" => metrics_storage.dup
+        }
+      end
+
+      def write!(repository_root: default_repository_root)
+        data = snapshot
+        return if data["lines"].empty? && data["metrics"].empty?
+
+        log_path = output_path(repository_root: repository_root, extension: "log")
+        json_path = output_path(repository_root: repository_root, extension: "json")
+        FileUtils.mkdir_p(File.dirname(log_path))
+        File.write(log_path, profile_header(data["meta"]) + data["lines"].join("\n") + "\n")
+        File.write(json_path, JSON.pretty_generate(data))
+        export_sidecars!(data, json_path)
+        $stdout.puts("\nBenchmark profile written to #{log_path}") if verbose?
+        log_path
+      end
+
+      def export_sidecars!(data, json_path)
+        formats = export_formats
+        return if formats.empty?
+
+        require_relative "report"
+        base = json_path.sub(/\.json\z/, "")
+        formats.each do |format|
+          path = "#{base}.#{export_extension(format)}"
+          File.write(path, Report.render(data, format: format))
+        end
+      end
+
+      def export_formats
+        raw = ENV["POLYRUN_BENCH_FORMATS"]
+        return [] if raw.nil? || raw.to_s.strip.empty?
+
+        raw.split(",").map(&:strip).reject(&:empty?)
+      end
+
+      def export_extension(format)
+        case format.to_s.downcase
+        when "markdown", "md" then "md"
+        when "text", "console", "txt" then "txt"
+        else format.to_s.downcase
+        end
+      end
+
+      def verbose?
+        %w[1 true yes].include?(ENV["POLYRUN_BENCH"]&.to_s&.downcase)
+      end
+
+      def output_path(repository_root: default_repository_root, extension: "log", commit_sha: nil, working_tree_clean: nil, timestamp: nil)
+        commit_identifier = commit_sha || self.commit_sha(repository_root: repository_root)
+        clean_tree = working_tree_clean.nil? ? working_tree_clean?(repository_root: repository_root) : working_tree_clean
+        filename = if clean_tree
+          "profile_#{commit_identifier}.#{extension}"
+        else
+          recorded_at = timestamp || self.timestamp
+          "profile_#{commit_identifier}_#{recorded_at}.#{extension}"
+        end
+
+        File.join(repository_root, "tmp", "benchmarks", filename)
+      end
+
+      def profile_meta(repository_root: default_repository_root)
+        {
+          "commit" => commit_sha(repository_root: repository_root),
+          "recorded_at" => Time.now.utc.iso8601,
+          "working_tree_clean" => working_tree_clean?(repository_root: repository_root),
+          "ruby" => RUBY_VERSION,
+          "polyrun_version" => Polyrun::VERSION
+        }
+      end
+
+      def profile_header(meta)
+        [
+          "# Benchmark profile",
+          "# commit: #{meta["commit"]}",
+          "# recorded_at: #{meta["recorded_at"]}",
+          "# working_tree_clean: #{meta["working_tree_clean"]}",
+          "# ruby: #{meta["ruby"]}",
+          ""
+        ].join("\n")
+      end
+
+      def commit_sha(repository_root: default_repository_root)
+        git_command("git rev-parse HEAD", repository_root: repository_root) || "unknown"
+      end
+
+      def working_tree_clean?(repository_root: default_repository_root)
+        git_command("git status --porcelain", repository_root: repository_root).to_s.empty?
+      end
+
+      def timestamp
+        Time.now.utc.strftime("%Y%m%d%H%M%S")
+      end
+
+      def git_command(command, repository_root:)
+        stdout, status = Open3.capture2(command, chdir: repository_root)
+        return nil unless status.success?
+
+        stdout.strip
+      rescue
+        nil
+      end
+
+      def detect_section_title(line)
+        return unless line.is_a?(String)
+        return if line.strip.empty?
+        return if line.start_with?("#")
+        return unless line.end_with?(":")
+
+        line.strip.delete_suffix(":")
+      end
+
+      def format_metric_line(metric)
+        value = metric["value"]
+        unit = metric["unit"]
+        suffix = (unit == "seconds") ? "s" : " #{unit}"
+        format("  %s: %s%s", metric["name"], value, suffix)
+      end
+
+      STORAGE_KEY = :polyrun_benchmark_profile_storage
+
+      def storage
+        Thread.current[STORAGE_KEY] ||= {
+          "lines" => [],
+          "metrics" => [],
+          "current_section" => ["default"]
+        }
+      end
+
+      def lines_storage
+        storage["lines"]
+      end
+
+      def metrics_storage
+        storage["metrics"]
+      end
+
+      def current_section_storage
+        storage["current_section"]
+      end
+
+      def default_repository_root
+        Dir.pwd
+      end
+    end
+  end
+end

data/lib/polyrun/benchmark/report.rb

@@ -0,0 +1,87 @@
+require "json"
+
+require_relative "../export/csv"
+require_relative "../export/markdown"
+
+module Polyrun
+  module Benchmark
+    # Formats benchmark profile JSON for humans and downstream tools.
+    module Report
+      METRIC_HEADERS = %w[section name value unit].freeze
+      LINE_HEADERS = %w[index text].freeze
+
+      module_function
+
+      def load(path)
+        ext = File.extname(path).downcase
+        if ext == ".json"
+          JSON.parse(File.read(path))
+        else
+          {"meta" => {}, "lines" => File.read(path).lines.map(&:chomp), "metrics" => []}
+        end
+      end
+
+      def render(data, format: "text")
+        case format.to_s.downcase
+        when "text", "console", "txt" then format_text(data)
+        when "json" then JSON.pretty_generate(data)
+        when "csv" then format_csv(data)
+        when "markdown", "md" then format_markdown(data)
+        else
+          raise Polyrun::Error, "report-benchmark: unknown format #{format.inspect} (use text, json, csv, or markdown)"
+        end
+      end
+
+      def format_text(data)
+        meta = data["meta"] || {}
+        header = [
+          "Benchmark profile",
+          "commit: #{meta["commit"]}",
+          "recorded_at: #{meta["recorded_at"]}",
+          "ruby: #{meta["ruby"]}",
+          ""
+        ]
+        (header + Array(data["lines"])).join("\n") + "\n"
+      end
+
+      def format_csv(data)
+        metrics = Array(data["metrics"])
+        if metrics.any?
+          rows = metrics.map { |metric| [metric["section"], metric["name"], metric["value"], metric["unit"]] }
+          return Export::Csv.generate(METRIC_HEADERS, rows)
+        end
+
+        rows = Array(data["lines"]).each_with_index.map { |line, index| [index + 1, line] }
+        Export::Csv.generate(LINE_HEADERS, rows)
+      end
+
+      def format_markdown(data)
+        meta = data["meta"] || {}
+        sections = [
+          {
+            heading: "Metadata",
+            headers: %w[key value],
+            rows: meta.sort_by { |key, _| key.to_s }
+          }
+        ]
+
+        metrics = Array(data["metrics"])
+        if metrics.any?
+          sections << {
+            heading: "Metrics",
+            headers: METRIC_HEADERS,
+            rows: metrics.map { |metric| [metric["section"], metric["name"], metric["value"], metric["unit"]] }
+          }
+        end
+
+        line_rows = Array(data["lines"]).reject(&:empty?).zip
+        sections << {
+          heading: "Log",
+          headers: %w[line],
+          rows: line_rows.empty? ? [["(empty)"]] : line_rows
+        }
+        Export::Markdown.document("Polyrun benchmark profile", sections)
+      end
+    end
+  end
+end

data/lib/polyrun/cli/benchmark_commands.rb

@@ -0,0 +1,66 @@
+require "optparse"
+
+require_relative "../benchmark/profile"
+require_relative "../benchmark/report"
+
+module Polyrun
+  class CLI
+    module BenchmarkCommands
+      private
+
+      def cmd_report_benchmark(argv)
+        input = nil
+        out_file = nil
+        report_format = "text"
+        OptionParser.new do |opts|
+          opts.banner = "usage: polyrun report-benchmark -i FILE [-o PATH] [--format text|json|csv|markdown]"
+          opts.on("-i", "--input PATH", "Benchmark profile .json or .log from tmp/benchmarks/") { |v| input = v }
+          opts.on("-o", "--output PATH", "Write report to file instead of stdout") { |v| out_file = v }
+          opts.on("--format VAL", "text (default), json, csv, or markdown") { |v| report_format = v }
+        end.parse!(argv)
+        input ||= argv.first
+
+        unless input && File.file?(input)
+          Polyrun::Log.warn "report-benchmark: need -i FILE"
+          return 2
+        end
+
+        data = Polyrun::Benchmark::Report.load(File.expand_path(input))
+        begin
+          text = Polyrun::Benchmark::Report.render(data, format: report_format)
+        rescue Polyrun::Error => e
+          Polyrun::Log.warn e.message.to_s
+          return 2
+        end
+
+        if out_file
+          File.write(File.expand_path(out_file), text)
+          Polyrun::Log.puts File.expand_path(out_file)
+        else
+          Polyrun::Log.print text
+        end
+        0
+      end
+
+      def cmd_bench(argv)
+        tag = "benchmark"
+        paths = %w[spec/performance/benchmark_spec.rb spec/performance/benchmark_merge_spec.rb]
+        env = {
+          "BENCH_FILES" => ENV.fetch("BENCH_FILES", "110"),
+          "BENCH_LINES" => ENV.fetch("BENCH_LINES", "310"),
+          "BENCH_FRAGMENTS" => ENV.fetch("BENCH_FRAGMENTS", "8"),
+          "BENCH_MERGE_REPS" => ENV.fetch("BENCH_MERGE_REPS", "3"),
+          "BENCH_LINE_COUNT_REPS" => ENV.fetch("BENCH_LINE_COUNT_REPS", "5"),
+          "BENCH_PEEK_REPS" => ENV.fetch("BENCH_PEEK_REPS", "200")
+        }
+        formats = ENV["POLYRUN_BENCH_FORMATS"]
+        env["POLYRUN_BENCH_FORMATS"] = formats if formats && !formats.to_s.strip.empty?
+        bench_argv = paths + ["--tag", tag]
+        bench_argv.concat(argv) unless argv.empty?
+        Polyrun::Log.warn "polyrun bench: running performance specs (#{paths.join(", ")})" if @verbose
+        success = system(env, "bundle", "exec", "rspec", *bench_argv)
+        success ? 0 : ($?.exitstatus || 1)
+      end
+    end
+  end
+end

data/lib/polyrun/cli/coverage_commands.rb

@@ -11,7 +11,7 @@ module Polyrun
 
       private
 
-      def cmd_merge_coverage(argv, _config_path)
+      def cmd_merge_coverage(argv, _config_path, print_console_summary: true)
         inputs, output, formats = merge_coverage_parse_argv(argv)
         if inputs.empty?
           Polyrun::Log.warn "merge-coverage: need at least one existing -i FILE (after glob expansion)"
@@ -36,7 +36,7 @@ module Polyrun
         payload = Polyrun::Coverage::Merge.to_simplecov_json(merged, meta: r[:meta], groups: r[:groups])
         out_abs = File.expand_path(output)
         merge_coverage_write_json_payload(out_abs, payload)
-        merge_coverage_write_format_outputs(merged, r, out_abs, formats)
+        merge_coverage_write_format_outputs(merged, r, out_abs, formats, print_console_summary: print_console_summary)
 
         elapsed = Process.clock_gettime(Process::CLOCK_MONOTONIC) - t0
         merge_coverage_log_finish(elapsed, inputs)
@@ -63,7 +63,7 @@ module Polyrun
         formats = Polyrun::Coverage::Reporting::DEFAULT_FORMATS.dup
 
         parser = OptionParser.new do |opts|
-          opts.banner = "usage: polyrun report-coverage -i FILE [-o DIR] [--basename NAME] [--format json,lcov,cobertura,console,html]"
+          opts.banner = "usage: polyrun report-coverage -i FILE [-o DIR] [--basename NAME] [--format json,lcov,cobertura,console,html,csv,markdown]"
           opts.on("-i", "--input PATH", "Merged or raw SimpleCov JSON") { |v| input = v }
           opts.on("-o", "--output DIR", "Output directory") { |v| output_dir = v }
           opts.on("--basename NAME", "File name prefix") { |v| basename = v }
@@ -122,7 +122,7 @@ module Polyrun
         files.each { |f| merge_argv.push("-i", f) }
         merge_argv += ["-o", output, "--format", format_list]
         Polyrun::Debug.time("merge-coverage (parent after workers)") do
-          cmd_merge_coverage(merge_argv, config_path)
+          cmd_merge_coverage(merge_argv, config_path, print_console_summary: coverage_console_output?)
         end
       end
 

data/lib/polyrun/cli/coverage_merge_io.rb

@@ -13,7 +13,7 @@ module Polyrun
         output = "coverage/polyrun-merged.json"
         formats = ["json"]
         parser = OptionParser.new do |opts|
-          opts.banner = "usage: polyrun merge-coverage -i FILE [-i FILE] [-o PATH] [--format json,lcov,cobertura,console,html]"
+          opts.banner = "usage: polyrun merge-coverage -i FILE [-i FILE] [-o PATH] [--format json,lcov,cobertura,console,html,csv,markdown]"
           opts.on("-i", "--input FILE", "Coverage JSON (repeatable; globs ok)") do |f|
             expand_merge_input_pattern(f).each { |x| inputs << x }
           end
@@ -39,11 +39,13 @@ module Polyrun
         end
       end
 
-      def merge_coverage_write_format_outputs(merged, r, out_abs, formats)
+      def merge_coverage_write_format_outputs(merged, r, out_abs, formats, print_console_summary: true)
         write_merge_lcov(merged, out_abs) if formats.include?("lcov")
         write_merge_cobertura(merged, r, out_abs) if formats.include?("cobertura")
-        write_merge_console(merged, out_abs) if formats.include?("console")
+        write_merge_console(merged, out_abs, print_summary: print_console_summary) if formats.include?("console")
         write_merge_html(merged, out_abs) if formats.include?("html")
+        write_merge_csv(merged, out_abs) if formats.include?("csv")
+        write_merge_markdown(merged, out_abs) if formats.include?("markdown")
       end
 
       def write_merge_lcov(merged, out_abs)
@@ -67,21 +69,45 @@ module Polyrun
         r[:meta]["polyrun_coverage_root"] || r[:meta][:polyrun_coverage_root]
       end
 
-      def write_merge_console(merged, out_abs)
+      def write_merge_console(merged, out_abs, print_summary: true)
         sum_path = out_abs.sub(/\.json\z/, "-summary.txt")
         sum_path = "#{out_abs}-summary.txt" if sum_path == out_abs
         summary = Polyrun::Coverage::Merge.console_summary(merged)
         summary_text = Polyrun::Coverage::Merge.format_console_summary(summary)
         Polyrun::Debug.time("write console summary") { File.write(sum_path, summary_text) }
+        return unless print_summary
+
         Polyrun::Log.print summary_text
       end
 
+      def coverage_console_output?
+        @verbose ||
+          %w[1 true yes].include?(ENV["POLYRUN_COVERAGE_VERBOSE"]&.to_s&.downcase) ||
+          Polyrun::Debug.enabled?
+      end
+
       def write_merge_html(merged, out_abs)
         html_path = out_abs.sub(/\.json\z/, ".html")
         html_path = "#{out_abs}.html" if html_path == out_abs
         Polyrun::Debug.time("write HTML report") { File.write(html_path, Polyrun::Coverage::Merge.emit_html(merged)) }
       end
 
+      def write_merge_csv(merged, out_abs)
+        csv_path = out_abs.sub(/\.json\z/, ".csv")
+        csv_path = "#{out_abs}.csv" if csv_path == out_abs
+        Polyrun::Debug.time("write CSV report") do
+          File.write(csv_path, Polyrun::Coverage::FileStatsReport.emit_csv(merged))
+        end
+      end
+
+      def write_merge_markdown(merged, out_abs)
+        markdown_path = out_abs.sub(/\.json\z/, ".md")
+        markdown_path = "#{out_abs}.md" if markdown_path == out_abs
+        Polyrun::Debug.time("write Markdown report") do
+          File.write(markdown_path, Polyrun::Coverage::FileStatsReport.emit_markdown(merged))
+        end
+      end
+
       def merge_coverage_log_finish(elapsed, inputs)
         thr = merge_slow_warn_threshold_seconds
         merge_coverage_warn_if_slow(elapsed, thr, inputs) if thr && elapsed > thr

data/lib/polyrun/cli/failure_commands.rb

@@ -36,12 +36,12 @@ module Polyrun
         output = File.join("tmp", "polyrun_failures", "merged.jsonl")
         format = "jsonl"
         OptionParser.new do |opts|
-          opts.banner = "usage: polyrun merge-failures -i FILE [-i FILE] [-o PATH] [--format jsonl|json]"
+          opts.banner = "usage: polyrun merge-failures -i FILE [-i FILE] [-o PATH] [--format jsonl|json|csv|markdown]"
           opts.on("-i", "--input FILE", "JSONL fragment or RSpec JSON (repeatable; globs ok)") do |f|
             expand_merge_input_pattern(f).each { |x| inputs << x }
           end
           opts.on("-o", "--output PATH", String) { |v| output = v }
-          opts.on("--format VAL", "jsonl (default) or json") { |v| format = v }
+          opts.on("--format VAL", "jsonl (default), json, csv, or markdown") { |v| format = v }
         end.parse!(argv)
         inputs.uniq!
         inputs.select! { |p| File.file?(p) }
@@ -75,6 +75,8 @@ module Polyrun
         return "jsonl" if f.empty?
         return "jsonl" if f == "jsonl"
         return "json" if f == "json"
+        return "csv" if f == "csv"
+        return "markdown" if %w[markdown md].include?(f)
 
         Polyrun::Log.warn "polyrun run-shards: unknown merge_failures_format=#{ctx[:merge_failures_format].inspect}; using jsonl"
         "jsonl"
@@ -84,7 +86,12 @@ module Polyrun
         raw = ctx[:merge_failures_output]
         return File.expand_path(raw) if raw && !raw.to_s.strip.empty?
 
-        ext = (fmt == "json") ? "json" : "jsonl"
+        ext = case fmt
+        when "json" then "json"
+        when "csv" then "csv"
+        when "markdown", "md" then "md"
+        else "jsonl"
+        end
         File.expand_path(File.join("tmp", "polyrun_failures", "merged.#{ext}"))
       end
     end

data/lib/polyrun/cli/help.rb

@@ -13,9 +13,11 @@ module Polyrun
             -h, --help
 
           Trace timing (stderr): DEBUG=1 or POLYRUN_DEBUG=1
-          Coverage: POLYRUN_COVERAGE=1 (or config/polyrun_coverage.yml + POLYRUN_QUICK_COVERAGE=1); POLYRUN_COVERAGE_DISABLE=1 skips; POLYRUN_COVERAGE_BRANCHES=1 for branch data in fragments
+          Coverage: POLYRUN_COVERAGE=1 (or config/polyrun_coverage.yml + POLYRUN_QUICK_COVERAGE=1); POLYRUN_COVERAGE_DISABLE=1 skips; POLYRUN_COVERAGE_BRANCHES=1 for branch data in fragments; POLYRUN_COVERAGE_VERBOSE=1 for per-worker and merged console summaries
+          Benchmark profiles: POLYRUN_BENCH=1 (stdout); JSON sidecar in tmp/benchmarks/; POLYRUN_BENCH_FORMATS=csv,markdown for extra exports; report-benchmark / bench
+          Hooks shell output: POLYRUN_HOOKS_VERBOSE=1 or -v / POLYRUN_VERBOSE=1 (or DEBUG); failures always print
           Merge profiling (stderr): POLYRUN_PROFILE_MERGE=1 (or verbose / DEBUG)
-          Post-merge formats (run-shards): POLYRUN_MERGE_FORMATS (default: json,lcov,cobertura,console,html)
+          Post-merge formats (run-shards): POLYRUN_MERGE_FORMATS (default: json,lcov,cobertura,console,html,csv,markdown)
           Start skips: POLYRUN_SKIP_BUILD_SPEC_PATHS=1, POLYRUN_START_SKIP_PREPARE=1, POLYRUN_START_SKIP_DATABASES=1
           Paths build skip: POLYRUN_SKIP_PATHS_BUILD=1
           Slow merge warning (seconds, default 10; 0 disables): POLYRUN_MERGE_SLOW_WARN_SECONDS
@@ -25,7 +27,7 @@ module Polyrun
           Per-worker idle timeout: --worker-idle-timeout SEC or POLYRUN_WORKER_IDLE_TIMEOUT_SEC after a progress ping (POLYRUN_WORKER_PING_FILE). Enable pings in test setup. Exit 125. Optional periodic pings: POLYRUN_WORKER_PING_THREAD=1 (POLYRUN_WORKER_PING_INTERVAL_SEC).
           Worker output routing (opt-in): POLYRUN_WORKER_OUTPUT_ROUTING=1 or POLYRUN_WORKER_LOG_DIR; per-shard logs under tmp/polyrun/workers (POLYRUN_WORKER_OUTPUT_PREFIX=0 for log-only)
           Example debug (RSpec, opt-in): POLYRUN_EXAMPLE_DEBUG=1; POLYRUN_DEBUG_SQL / POLYRUN_DEBUG_TRACE
-          Sharded formatter compat: progress formatters (e.g. Fuubar) under POLYRUN_SHARD_* (see docs/SETUP_PROFILE.md)
+          Sharded formatter compat: silences per-worker seed, summary, and pending lines under POLYRUN_SHARD_* (see docs/SETUP_PROFILE.md)
           Orchestration warnings on process stderr: POLYRUN_ORCHESTRATION_STDERR=1
           Spec quality (opt-in): POLYRUN_SPEC_QUALITY=1; run-shards --merge-spec-quality; merge-spec-quality / report-spec-quality
           Partition timing granularity (default file): POLYRUN_TIMING_GRANULARITY=file|example (experimental; see partition.timing_granularity)
@@ -35,8 +37,8 @@ module Polyrun
             version              print version
             plan                 emit partition manifest JSON
             prepare              run prepare recipe: default | assets (optional prepare.command overrides bin/rails assets:precompile) | shell (prepare.command required)
-            merge-coverage       merge SimpleCov JSON fragments (json/lcov/cobertura/console)
-            merge-failures       merge per-shard failure JSONL fragments or RSpec JSON files (jsonl/json)
+            merge-coverage       merge SimpleCov JSON fragments (json/lcov/cobertura/console/html/csv/markdown)
+            merge-failures       merge per-shard failure JSONL fragments or RSpec JSON files (jsonl/json/csv/markdown)
             run-shards           fan out N parallel OS processes (POLYRUN_SHARD_*; not Ruby threads); optional --merge-coverage / --merge-failures / --merge-spec-quality
             parallel-rspec       run-shards + merge-coverage (defaults to: bundle exec rspec after --)
             start                parallel-rspec; auto-runs prepare (shell/assets) and db:setup-* when polyrun.yml configures them; legacy script/build_spec_paths.rb if paths_build absent
@@ -49,11 +51,13 @@ module Polyrun
             quick                quick test runner (describe/it, before/after, let, expect…to, assert_*; optional capybara!)
             hook run <phase>     run one shell hook from polyrun.yml hooks: (e.g. before_suite); optional --shard/--total
             report-coverage      write all coverage formats from one JSON file
-            report-junit         RSpec JSON or Polyrun testcase JSON → JUnit XML (CI)
-            report-timing        print slow-file summary from merged timing JSON
+            report-junit         RSpec JSON or Polyrun testcase JSON → JUnit XML, CSV, or Markdown
+            report-timing        slow-file summary from merged timing JSON (text/csv/markdown)
+            report-benchmark     benchmark profile export from tmp/benchmarks/profile_*.json
+            bench                run performance benchmark specs (same as rake bench_performance)
             merge-timing         merge polyrun_timing_*.json shards
             merge-spec-quality   merge polyrun-spec-quality-fragment-*.jsonl shards
-            report-spec-quality  spec quality report from merged JSON (zero-hit, hot lines, churn)
+            report-spec-quality  spec quality report from merged JSON (text/json/csv/markdown)
             config               print effective config by dotted path (loaded YAML plus merged prepare.env, resolved partition shard fields, workers)
             env                  print shard + database env (see polyrun.yml databases)
             db:setup-template    migrate template DB (PostgreSQL)

data/lib/polyrun/cli/report_commands.rb

@@ -7,7 +7,7 @@ module Polyrun
       private
 
       def cmd_report_junit(argv)
-        inputs, output = report_junit_parse_inputs(argv)
+        inputs, output, report_format = report_junit_parse_inputs(argv)
         inputs.uniq!
         if inputs.empty?
           Polyrun::Log.warn "report-junit: need -i FILE (existing path after glob expansion)"
@@ -17,12 +17,12 @@ module Polyrun
         inputs = inputs.map { |p| File.expand_path(p) }
         return 2 unless report_junit_inputs_exist?(inputs)
 
-        out = report_junit_resolved_output(inputs, output)
+        out = report_junit_resolved_output(inputs, output, report_format)
         path =
           if inputs.size == 1
-            Polyrun::Reporting::Junit.write_from_json_file(inputs.first, output_path: out)
+            Polyrun::Reporting::Junit.write_from_json_file(inputs.first, output_path: out, format: report_format)
           else
-            Polyrun::Reporting::Junit.merge_rspec_json_files(inputs, output_path: out)
+            Polyrun::Reporting::Junit.merge_rspec_json_files(inputs, output_path: out, format: report_format)
           end
         Polyrun::Log.puts path
         0
@@ -31,17 +31,19 @@ module Polyrun
       def report_junit_parse_inputs(argv)
         inputs = []
         output = nil
+        report_format = "xml"
         OptionParser.new do |opts|
-          opts.banner = "usage: polyrun report-junit -i FILE [-i FILE]... [-o PATH]"
+          opts.banner = "usage: polyrun report-junit -i FILE [-i FILE]... [-o PATH] [--format xml|csv|markdown]"
           opts.on("-i", "--input PATH", "RSpec JSON (repeatable; globs ok; multiple files merge examples)") do |v|
             expand_merge_input_pattern(v).each { |x| inputs << x }
           end
-          opts.on("-o", "--output PATH", "Default: <dir of first input>/junit.xml") { |v| output = v }
+          opts.on("-o", "--output PATH", "Default: <dir of first input>/junit.<ext>") { |v| output = v }
+          opts.on("--format VAL", "xml (default), csv, or markdown") { |v| report_format = v }
         end.parse!(argv)
         if inputs.empty? && argv.first
           expand_merge_input_pattern(argv.first).each { |x| inputs << x }
         end
-        [inputs, output]
+        [inputs, output, report_format]
       end
 
       def report_junit_inputs_exist?(inputs)
@@ -54,11 +56,16 @@ module Polyrun
         true
       end
 
-      def report_junit_resolved_output(inputs, output)
+      def report_junit_resolved_output(inputs, output, format)
         if output
           File.expand_path(output)
         else
-          File.join(File.dirname(inputs.first), "junit.xml")
+          extension = case format.to_s.downcase
+          when "csv" then "csv"
+          when "markdown", "md" then "md"
+          else "xml"
+          end
+          File.join(File.dirname(inputs.first), "junit.#{extension}")
         end
       end
 
@@ -66,11 +73,13 @@ module Polyrun
         input = nil
         out_file = nil
         top = 30
+        report_format = "text"
         OptionParser.new do |opts|
-          opts.banner = "usage: polyrun report-timing -i FILE [-o PATH] [--top N]"
+          opts.banner = "usage: polyrun report-timing -i FILE [-o PATH] [--top N] [--format text|csv|markdown]"
           opts.on("-i", "--input PATH", "Merged polyrun_timing.json (path => seconds)") { |v| input = v }
           opts.on("-o", "--output PATH", "Write summary to file instead of stdout") { |v| out_file = v }
           opts.on("--top N", Integer) { |v| top = v }
+          opts.on("--format VAL", "text (default), csv, or markdown") { |v| report_format = v }
         end.parse!(argv)
         input ||= argv.first
 
@@ -80,7 +89,12 @@ module Polyrun
         end
 
         merged = JSON.parse(File.read(File.expand_path(input)))
-        text = Polyrun::Timing::Summary.format_slow_files(merged, top: top)
+        begin
+          text = Polyrun::Timing::Summary.render(merged, format: report_format, top: top)
+        rescue Polyrun::Error => e
+          Polyrun::Log.warn e.message.to_s
+          return 2
+        end
         if out_file
           File.write(File.expand_path(out_file), text)
           Polyrun::Log.puts File.expand_path(out_file)

data/lib/polyrun/cli/run_shards_parallel_children.rb

@@ -23,7 +23,7 @@ module Polyrun
         mt = ctx[:matrix_shard_total]
 
         pids = []
-        Polyrun::WorkerOutput.prepare_log_dir! if Polyrun::WorkerOutput.routing_enabled? && parallel
+        Polyrun::WorkerOutput.prepare_log_dir! if Polyrun::WorkerOutput.routing_enabled?
         workers.times do |shard|
           paths = plan.shard(shard)
           if paths.empty?

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 }