polyrun 1.0.0

data/lib/polyrun/quick/runner.rb

@@ -0,0 +1,180 @@
+require "pathname"
+
+require_relative "assertions"
+require_relative "errors"
+require_relative "example_group"
+require_relative "example_runner"
+require_relative "reporter"
+
+module Polyrun
+  # Micro test runner: nested +describe+, +it+ / +test+, +before+ / +after+, +let+ / +let!+,
+  # +expect().to+ matchers, optional +Polyrun::Quick.capybara!+ when the +capybara+ gem is loaded.
+  #
+  # Run: +polyrun quick+ or +polyrun quick spec/foo.rb+
+  #
+  # Coverage: when +POLYRUN_COVERAGE=1+ or (+config/polyrun_coverage.yml+ and +POLYRUN_QUICK_COVERAGE=1+), starts
+  # {Polyrun::Coverage::Rails} before loading quick files so stdlib +Coverage+ records them.
+  module Quick
+    module DSL
+      def describe(name, &block)
+        Quick.describe(name, &block)
+      end
+    end
+
+    class Collector
+      attr_reader :groups
+
+      def initialize
+        @groups = []
+      end
+
+      def register(group)
+        @groups << group
+      end
+    end
+
+    # rubocop:disable ThreadSafety/ClassAndModuleAttributes, ThreadSafety/ClassInstanceVariable
+    class << self
+      attr_accessor :collector
+
+      def capybara!
+        @capybara_enabled = true
+      end
+
+      def capybara?
+        @capybara_enabled == true
+      end
+
+      def reset_capybara_flag!
+        @capybara_enabled = false
+      end
+
+      def describe(name, &block)
+        group = ExampleGroup.new(name)
+        group.instance_eval(&block) if block
+        (collector || raise(Error, "Polyrun::Quick.describe used outside polyrun quick")).register(group)
+      end
+    end
+    # rubocop:enable ThreadSafety/ClassAndModuleAttributes, ThreadSafety/ClassInstanceVariable
+
+    class Runner
+      def self.run(paths:, out: $stdout, err: $stderr, verbose: false)
+        new(out: out, err: err, verbose: verbose).run(paths)
+      end
+
+      def initialize(out: $stdout, err: $stderr, verbose: false)
+        @out = out
+        @err = err
+        @verbose = verbose
+      end
+
+      def run(paths)
+        Quick.reset_capybara_flag!
+
+        files = expand_paths(paths)
+        if files.empty?
+          Polyrun::Log.warn "polyrun quick: no files (pass paths or add Quick files under spec/ or test/, e.g. spec/polyrun_quick/**/*.rb or spec/**/*.rb excluding *_spec.rb / *_test.rb)"
+          return 2
+        end
+
+        quick_start_coverage_if_configured!
+
+        collector = load_quick_files!(files)
+        return 1 unless collector
+
+        reporter = Reporter.new(@out, @err, @verbose)
+        run_examples!(collector, reporter)
+        reporter.summary
+      ensure
+        Quick.collector = nil
+        Quick.reset_capybara_flag!
+      end
+
+      def load_quick_files!(files)
+        collector = Collector.new
+        Quick.collector = collector
+
+        files.each do |path|
+          code = File.read(path)
+          loader = Object.new
+          loader.extend(DSL)
+          loader.instance_eval(code, path, 1)
+        rescue SyntaxError, StandardError => e
+          Polyrun::Log.warn "polyrun quick: failed to load #{path}: #{e.class}: #{e.message}"
+          Quick.collector = nil
+          return nil
+        end
+
+        Quick.collector = nil
+        collector
+      end
+
+      def run_examples!(collector, reporter)
+        collector.groups.each do |root|
+          root.each_example_with_ancestors do |chain, desc, block|
+            inner = chain.last
+            example_runner = ExampleRunner.new(reporter)
+            example_runner.run(
+              group_name: inner.full_name,
+              description: desc,
+              ancestor_chain: chain,
+              block: block
+            )
+          end
+        end
+      end
+
+      def quick_start_coverage_if_configured!
+        return unless Polyrun::Coverage::Collector.coverage_requested_for_quick?(Dir.pwd)
+        return if Polyrun::Coverage::Collector.started?
+
+        require_relative "../coverage/rails"
+        Polyrun::Coverage::Rails.start!(
+          root: File.expand_path(Dir.pwd),
+          meta: {"command_name" => "polyrun quick"}
+        )
+      end
+
+      def expand_paths(paths)
+        return default_globs if paths.nil? || paths.empty?
+
+        paths.flat_map do |p|
+          expanded = File.expand_path(p)
+          if File.directory?(expanded)
+            Dir.glob(File.join(expanded, "**", "*.rb")).sort
+          elsif /[*?\[]/.match?(p)
+            Dir.glob(File.expand_path(p)).sort
+          elsif File.file?(expanded)
+            [expanded]
+          else
+            []
+          end
+        end.uniq
+      end
+
+      def default_globs
+        base = File.expand_path(Dir.pwd)
+        globs = [
+          File.join(base, "spec", "polyrun_quick", "**", "*.rb"),
+          File.join(base, "test", "polyrun_quick", "**", "*.rb"),
+          File.join(base, "spec", "**", "*.rb"),
+          File.join(base, "test", "**", "*.rb")
+        ]
+        globs.flat_map { |g| Dir.glob(g) }.uniq.reject { |p| default_quick_exclude?(p, base) }.sort
+      end
+
+      # Omit RSpec/Minitest files and common helpers so +polyrun quick+ with no args does not load normal suites.
+      def default_quick_exclude?(path, base)
+        rel = Pathname.new(path).relative_path_from(Pathname.new(base)).to_s
+        parts = rel.split(File::SEPARATOR)
+        bn = File.basename(path)
+        return true if bn.end_with?("_spec.rb", "_test.rb")
+        return true if %w[spec_helper.rb rails_helper.rb test_helper.rb].include?(bn)
+        return true if parts[0] == "spec" && %w[support fixtures factories].include?(parts[1])
+        return true if parts[0] == "test" && %w[support fixtures].include?(parts[1])
+
+        false
+      end
+    end
+  end
+end

data/lib/polyrun/quick.rb

@@ -0,0 +1 @@
+require_relative "quick/runner"

data/lib/polyrun/railtie.rb

@@ -0,0 +1,7 @@
+module Polyrun
+  # Optional Rails integration. Coverage must still be started from +spec_helper.rb+ (before the app loads) via
+  # {Polyrun::Coverage::Rails.start!}; this railtie only registers the gem with Rails.
+  class Railtie < ::Rails::Railtie
+    railtie_name :polyrun
+  end
+end

data/lib/polyrun/reporting/junit.rb

@@ -0,0 +1,125 @@
+require "cgi"
+require "json"
+
+module Polyrun
+  module Reporting
+    # JUnit XML for CI (replaces rspec_junit_formatter) — stdlib only.
+    #
+    # Input JSON may be:
+    # - **RSpec JSON** — output of +rspec --format json --out rspec.json+ (+examples+ array).
+    # - **Polyrun canonical** — +{ "name" => "...", "testcases" => [ ... ] }+ (see +emit_xml+).
+    #
+    # Each testcase hash supports: +classname+, +name+, +time+, +status+ (+passed+, +failed+, +pending+/+skipped+),
+    # and optional +failure+ => +{ "message" => "...", "body" => "..." }+.
+    module Junit
+      module_function
+
+      def write_from_json_file(json_path, output_path:)
+        data = JSON.parse(File.read(json_path))
+        write_from_hash(data, output_path: output_path)
+      end
+
+      # Merge several RSpec JSON outputs (parallel shards) by concatenating +examples+.
+      def merge_rspec_json_files(paths, output_path:)
+        merged = {"examples" => []}
+        paths.each do |p|
+          data = JSON.parse(File.read(p))
+          merged["examples"].concat(data["examples"] || [])
+        end
+        merged["summary"] = {"summary_line" => "merged #{paths.size} RSpec JSON file(s)"}
+        write_from_hash(merged, output_path: output_path)
+      end
+
+      def write_from_hash(data, output_path:)
+        doc = parse_input(data)
+        xml = emit_xml(doc)
+        File.write(output_path, xml)
+        output_path
+      end
+
+      def parse_input(data)
+        raise Polyrun::Error, "JUnit input must be a Hash" unless data.is_a?(Hash)
+
+        if data["examples"].is_a?(Array)
+          from_rspec_json(data)
+        elsif data["testcases"].is_a?(Array)
+          from_polyrun_hash(data)
+        else
+          raise Polyrun::Error,
+            'JUnit input: expected top-level "examples" (RSpec JSON) or "testcases" (Polyrun schema)'
+        end
+      end
+
+      def from_rspec_json(data)
+        cases = []
+        data["examples"].each do |ex|
+          next unless ex.is_a?(Hash)
+
+          cases << junit_rspec_example_to_case(ex)
+        end
+
+        name = (data.dig("summary", "summary_line") || data["name"] || "RSpec").to_s
+        from_polyrun_hash("name" => name, "hostname" => hostname, "testcases" => cases)
+      end
+
+      def junit_rspec_example_to_case(ex)
+        status = (ex["status"] || "unknown").to_s
+        file = ex["file_path"].to_s.sub(%r{\A\./}, "")
+        tc = {
+          "classname" => file.empty? ? "rspec" : file,
+          "name" => (ex["full_description"] || ex["description"] || ex["id"]).to_s,
+          "time" => (ex["run_time"] || ex["time"] || 0).to_f,
+          "status" => status
+        }
+        if status == "failed"
+          tc["failure"] = junit_rspec_failure_hash(ex)
+        end
+        tc
+      end
+
+      def junit_rspec_failure_hash(ex)
+        e = ex["exception"]
+        if e.is_a?(Hash)
+          {
+            "message" => e["message"].to_s,
+            "body" => Array(e["backtrace"]).join("\n")
+          }
+        else
+          {"message" => "failed", "body" => ex.inspect}
+        end
+      end
+
+      def from_polyrun_hash(data)
+        {
+          "name" => (data["name"] || data["testsuite_name"] || "tests").to_s,
+          "hostname" => (data["hostname"] || hostname).to_s,
+          "testcases" => Array(data["testcases"])
+        }
+      end
+
+      def hostname
+        require "socket"
+        Socket.gethostname
+      rescue
+        "localhost"
+      end
+
+      def status_of(c)
+        s = (c["status"] || c[:status] || "passed").to_s
+        return "skipped" if s == "pending"
+
+        s
+      end
+
+      def format_float(x)
+        format("%.6f", x.to_f)
+      end
+
+      def esc(s)
+        CGI.escapeHTML(s.to_s)
+      end
+    end
+  end
+end
+
+require_relative "junit_emit"

data/lib/polyrun/reporting/junit_emit.rb

@@ -0,0 +1,58 @@
+module Polyrun
+  module Reporting
+    module Junit
+      module_function
+
+      # +doc+ is +{ "name", "hostname", "testcases" => [ ... ] }+
+      def emit_xml(doc)
+        cases = doc["testcases"] || []
+        lines = []
+        lines << junit_xml_header(doc, cases)
+        cases.each do |c|
+          lines << junit_xml_testcase_line(c)
+        end
+        lines << %(</testsuite>)
+        lines << %(</testsuites>)
+        lines.join("\n") + "\n"
+      end
+
+      def junit_xml_header(doc, cases)
+        total_time = cases.sum { |c| (c["time"] || c[:time] || 0).to_f }
+        failures = cases.count { |c| status_of(c) == "failed" }
+        errors = cases.count { |c| status_of(c) == "error" }
+        skipped = cases.count { |c| %w[pending skipped].include?(status_of(c)) }
+        tests = cases.size
+        lines = []
+        lines << %(<?xml version="1.0" encoding="UTF-8"?>)
+        lines << %(<testsuites name="#{esc(doc["name"])}">)
+        lines << %(<testsuite name="#{esc(doc["name"])}" tests="#{tests}" failures="#{failures}" errors="#{errors}" skipped="#{skipped}" time="#{format_float(total_time)}" hostname="#{esc(doc["hostname"])}">)
+        lines.join("\n")
+      end
+
+      def junit_xml_testcase_line(c)
+        c = c.transform_keys(&:to_s)
+        classname = c["classname"].to_s
+        name = c["name"].to_s
+        time = (c["time"] || 0).to_f
+        lines = []
+        lines << %(<testcase classname="#{esc(classname)}" name="#{esc(name)}" file="#{esc(c["file"] || classname)}" line="#{esc(c["line"] || "")}" time="#{format_float(time)}">)
+        case status_of(c)
+        when "failed", "error"
+          lines << junit_xml_failure_body(c)
+        when "pending", "skipped"
+          lines << %(<skipped/>)
+        end
+        lines << %(</testcase>)
+        lines.join("\n")
+      end
+
+      def junit_xml_failure_body(c)
+        f = c["failure"] || {}
+        fm = f["message"] || f[:message] || status_of(c)
+        fb = f["body"] || f[:body] || ""
+        tag = (status_of(c) == "error") ? "error" : "failure"
+        %(<#{tag} message="#{esc(fm)}">#{esc(fb)}</#{tag}>)
+      end
+    end
+  end
+end

data/lib/polyrun/reporting/rspec_junit.rb

@@ -0,0 +1,39 @@
+require "fileutils"
+
+module Polyrun
+  module Reporting
+    # CI: emit JUnit XML from RSpec's JSON formatter output (replaces +rspec_junit_formatter+).
+    #
+    #   require "polyrun/reporting/rspec_junit"
+    #   Polyrun::Reporting::RspecJunit.install!(only_if: -> { ENV["CI"] })
+    #
+    # Ensure +.rspec+ or CLI keeps a human formatter (e.g. documentation) in addition to JSON.
+    module RspecJunit
+      module_function
+
+      def install!(json_path: "rspec.json", junit_path: "coverage/junit-coverage.xml", only_if: nil)
+        pred = only_if || -> { ENV["CI"] }
+        return unless pred.call
+
+        json_abs = File.expand_path(json_path)
+        FileUtils.mkdir_p(File.dirname(json_abs))
+
+        require "rspec/core"
+        require "rspec/core/formatters/json_formatter"
+
+        RSpec.configure do |config|
+          config.add_formatter RSpec::Core::Formatters::JsonFormatter, json_abs
+        end
+
+        at_exit do
+          next unless pred.call
+
+          FileUtils.mkdir_p(File.dirname(File.expand_path(junit_path)))
+          if File.file?(json_abs)
+            Junit.write_from_json_file(json_abs, output_path: junit_path)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/polyrun/rspec.rb

@@ -0,0 +1,15 @@
+require_relative "../polyrun"
+
+module Polyrun
+  # Optional RSpec wiring (require +polyrun/rspec+ explicitly).
+  module RSpec
+    module_function
+
+    # Registers +before(:suite)+ to run {Data::ParallelProvisioning.run_suite_hooks!}.
+    def install_parallel_provisioning!(rspec_config)
+      rspec_config.before(:suite) do
+        Polyrun::Data::ParallelProvisioning.run_suite_hooks!
+      end
+    end
+  end
+end

data/lib/polyrun/templates/POLYRUN.md

@@ -0,0 +1,45 @@
+# Polyrun in this project
+
+This repo uses [Polyrun](https://github.com/amkisko/polyrun.rb) for parallel RSpec, merged coverage, and optional CI report formats.
+
+## Setup profile
+
+Fill in and keep updated: dimensions are summarized in Polyrun’s [SETUP_PROFILE checklist](https://github.com/amkisko/polyrun.rb/blob/main/docs/SETUP_PROFILE.md) (project type, DB, prepare, CI model).
+
+## Canonical commands
+
+```bash
+bundle exec polyrun -c polyrun.yml build-paths
+bundle exec polyrun -c polyrun.yml parallel-rspec --workers 5
+```
+
+Adjust `--workers` or use `bin/rspec_parallel` if your repo provides a wrapper.
+
+## CI model (choose one and match your workflows)
+
+### Model A — single CI job, N worker processes on one runner
+
+- Run `polyrun -c polyrun.yml parallel-rspec --workers N` (or `polyrun start`).
+- Merge coverage in the same job (or a follow-up step) from `coverage/polyrun-fragment-*.json`.
+
+### Model B — matrix: one shard per job
+
+- Matrix sets `POLYRUN_SHARD_INDEX` and `POLYRUN_SHARD_TOTAL` explicitly (many runners do not set `CI_NODE_*` by default).
+- Each job runs `polyrun build-paths`, `polyrun plan`, then `bundle exec rspec` for that shard only (see `bin/polyrun-rspec` or `bin/rspec_ci_shard` patterns).
+- Upload `coverage/polyrun-fragment-<shard>.json` per job; a `merge-coverage` job downloads all fragments and merges.
+
+Do not combine Model A and Model B in one workflow without a documented reason (nested parallelism and duplicate merges).
+
+## Configuration contract
+
+- `polyrun.yml` — partition, optional `prepare`, optional `databases`. This file is the source of truth for shard indices and paths.
+- Adapters — thin scripts (`bin/rspec_parallel`, `bin/polyrun-rspec`, `database.yml` ERB, prepare scripts) must match `polyrun.yml`.
+
+## Coverage
+
+- `spec/spec_helper.rb`: `require "polyrun"` and collector or Rails helper as appropriate.
+- Fragments: `coverage/polyrun-fragment-<shard>.json` → `polyrun merge-coverage` → `polyrun report-coverage` / `report-junit` for CI.
+
+## Further reading
+
+- Polyrun README: partition, prepare, databases, merge-coverage, `Polyrun::Env::Ci`

data/lib/polyrun/templates/ci_matrix.polyrun.yml

@@ -0,0 +1,14 @@
+# Polyrun — partition contract for CI matrix (one job per POLYRUN_SHARD_INDEX).
+# Each matrix row: set POLYRUN_SHARD_INDEX and POLYRUN_SHARD_TOTAL; run build-paths, plan, rspec.
+# A separate CI job downloads coverage/polyrun-fragment-*.json and runs merge-coverage.
+# Do not use parallel-rspec with multiple workers inside the same matrix row unless you intend nested parallelism.
+# See: docs/SETUP_PROFILE.md
+
+partition:
+  paths_file: spec/spec_paths.txt
+  shard_total: 5
+  shard_index: 0
+  strategy: round_robin
+  paths_build:
+    all_glob: spec/**/*_spec.rb
+    stages: []

data/lib/polyrun/templates/minimal_gem.polyrun.yml

@@ -0,0 +1,13 @@
+# Polyrun — minimal gem/library layout (no Rails prepare, no databases: block).
+# Fill in paths_build.stages if you need regex or substring ordering for slow specs.
+# Next: spec_helper — require "polyrun" + Polyrun::Coverage::Collector (or your collector config)
+# See: docs/SETUP_PROFILE.md
+
+partition:
+  paths_file: spec/spec_paths.txt
+  shard_total: 5
+  shard_index: 0
+  strategy: round_robin
+  paths_build:
+    all_glob: spec/**/*_spec.rb
+    stages: []

data/lib/polyrun/templates/rails_prepare.polyrun.yml

@@ -0,0 +1,31 @@
+# Polyrun — Rails app with one-shot prepare before parallel workers.
+# Adjust prepare.command to your repo (assets, Playwright, webapp build, etc.).
+# Gate per-worker duplicate work in application code when POLYRUN_SHARD_TOTAL > 1.
+# See: docs/SETUP_PROFILE.md
+
+partition:
+  paths_file: spec/spec_paths.txt
+  shard_total: 5
+  shard_index: 0
+  strategy: round_robin
+  paths_build:
+    all_glob: spec/**/*_spec.rb
+    stages: []
+
+prepare:
+  recipe: shell
+  rails_root: .
+  command: bundle exec ruby bin/test_prepare.rb
+
+# Uncomment and edit when using Postgres template + per-shard DB names from polyrun env:
+# databases:
+#   template_db: my_app_template
+#   shard_db_pattern: "my_app_test_%{shard}"
+#   postgresql:
+#     host: localhost
+#     username: postgres
+#   connections:
+#     - name: analytics
+#       template_db: my_app_analytics_template   # second migrate + CREATE … TEMPLATE for parallel tests
+#       shard_db_pattern: "my_app_analytics_test_%{shard}"
+#       env_key: ANALYTICS_DATABASE_URL          # must match database.yml / Rails multi-db

data/lib/polyrun/timing/merge.rb

@@ -0,0 +1,35 @@
+require "json"
+
+require_relative "../debug"
+
+module Polyrun
+  module Timing
+    # Merges per-shard timing JSON files (spec2 §2.4): path => wall seconds (float).
+    # Disjoint suites: values merged by taking the maximum per path when duplicates appear.
+    module Merge
+      module_function
+
+      def merge_files(paths)
+        merged = {}
+        paths.each do |p|
+          data = JSON.parse(File.read(p))
+          next unless data.is_a?(Hash)
+
+          data.each do |file, sec|
+            f = file.to_s
+            t = sec.to_f
+            merged[f] = merged.key?(f) ? [merged[f], t].max : t
+          end
+        end
+        merged
+      end
+
+      def merge_and_write(paths, output_path)
+        Polyrun::Debug.log_kv(merge_timing: "merge_and_write", input_count: paths.size, output_path: output_path)
+        merged = Polyrun::Debug.time("Timing::Merge.merge_files") { merge_files(paths) }
+        Polyrun::Debug.time("Timing::Merge.write JSON") { File.write(output_path, JSON.pretty_generate(merged)) }
+        merged
+      end
+    end
+  end
+end

data/lib/polyrun/timing/summary.rb

@@ -0,0 +1,25 @@
+module Polyrun
+  module Timing
+    # Human-readable slow-file list from merged timing JSON (per-file cost).
+    module Summary
+      module_function
+
+      # +merged+ is path (String) => seconds (Float), as produced by +Timing::Merge.merge_files+.
+      def format_slow_files(merged, top: 30, title: "Polyrun slowest files (by wall time, seconds)")
+        return "#{title}\n  (no data)\n" if merged.nil? || merged.empty?
+
+        pairs = merged.sort_by { |_, sec| -sec.to_f }.first(Integer(top))
+        lines = [title, ""]
+        pairs.each_with_index do |(path, sec), i|
+          lines << format("  %2d. %s  %.4f", i + 1, path, sec.to_f)
+        end
+        lines.join("\n") + "\n"
+      end
+
+      def write_file(merged, path, **kwargs)
+        File.write(path, format_slow_files(merged, **kwargs))
+        path
+      end
+    end
+  end
+end

data/lib/polyrun/version.rb

@@ -0,0 +1,3 @@
+module Polyrun
+  VERSION = "1.0.0"
+end

data/lib/polyrun.rb

@@ -0,0 +1,58 @@
+require_relative "polyrun/version"
+require_relative "polyrun/log"
+require_relative "polyrun/debug"
+require_relative "polyrun/config"
+require_relative "polyrun/coverage/merge"
+require_relative "polyrun/coverage/filter"
+require_relative "polyrun/coverage/result"
+require_relative "polyrun/coverage/formatter"
+require_relative "polyrun/coverage/collector"
+require_relative "polyrun/coverage/reporting"
+require_relative "polyrun/coverage/rails"
+require_relative "polyrun/partition/plan"
+require_relative "polyrun/partition/paths"
+require_relative "polyrun/partition/paths_build"
+require_relative "polyrun/queue/file_store"
+require_relative "polyrun/data/fixtures"
+require_relative "polyrun/data/cached_fixtures"
+require_relative "polyrun/data/parallel_provisioning"
+require_relative "polyrun/data/factory_instrumentation"
+require_relative "polyrun/data/snapshot"
+require_relative "polyrun/data/factory_counts"
+require_relative "polyrun/prepare/assets"
+require_relative "polyrun/prepare/artifacts"
+require_relative "polyrun/database/shard"
+require_relative "polyrun/database/url_builder"
+require_relative "polyrun/database/provision"
+require_relative "polyrun/database/clone_shards"
+require_relative "polyrun/env/ci"
+require_relative "polyrun/timing/merge"
+require_relative "polyrun/timing/summary"
+require_relative "polyrun/reporting/junit"
+# RSpec JSON formatter + JUnit is opt-in: require "polyrun/reporting/rspec_junit" (loads RSpec only inside RspecJunit.install!).
+require_relative "polyrun/cli"
+
+if defined?(Rails::Railtie)
+  require_relative "polyrun/railtie"
+end
+
+module Polyrun
+  class Error < StandardError; end
+
+  # Delegate to {Polyrun::Log} for swappable stderr/stdout (CLI and library messages).
+  def self.stderr=(io)
+    Log.stderr = io
+  end
+
+  def self.stderr
+    Log.stderr
+  end
+
+  def self.stdout=(io)
+    Log.stdout = io
+  end
+
+  def self.stdout
+    Log.stdout
+  end
+end