polyrun 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: ca0c4afee7136f1cdf3ffe319d55c08457323119102a0a4d01478b02df91ce31
+  data.tar.gz: d468805765ee230bed530fdce182f189c0521e3dff7516be5c75bc620c362fc8
+SHA512:
+  metadata.gz: 98e04c5388e51da737bb73407497830d82bf61daabdfd77e9024fd2d973663dfed934c87691c6f2e864d7642e457a1eaaff27e3cf3f79bfa102a92ec9a0034aa
+  data.tar.gz: b6c407039df97914ed8e07a04bdb0dc4c8e044d9b0ffd3802e44e600a6c4002fe22b8673266263c5981bb4bde90246c992defb589eb3b785952b0c56f67c263e

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,31 @@
+# Code of Conduct
+
+## Our pledge
+
+We pledge to make participation in the Polyrun community a harassment-free experience for everyone. We operate on principles of mutual respect, privacy, and authentic engagement. We value substantive contributions and clarity on intentions.
+
+## Our standards
+
+Examples of behavior that contributes to a positive environment include:
+
+- Authenticity: engaging with genuine curiosity and admitting uncertainty rather than feigning knowledge.
+- Responsible innovation: taking full responsibility for any content or code contributed, whether manually written or generated by automation tools.
+- Gentle correction: responding politely to errors. We view mistakes as opportunities for learning, provided they are addressed with humility.
+- Inclusive language: using language that welcomes diverse perspectives and respects the privacy and identity of all participants.
+
+Examples of unacceptable behavior include:
+
+- Harassment: public or private harassment, trolling, or insulting comments.
+- Weaponized complexity: using jargon or overwhelming volume (including automated spam) to silence others.
+- Publishing private information: sharing others' data or personal context without explicit permission.
+
+## Artificial intelligence and automation
+
+In accordance with our commitment to collective awareness:
+
+- Contributors are responsible for the accuracy and security of any AI-generated artifacts they submit.
+- "The AI wrote it" is not a valid excuse for introducing bugs, security vulnerabilities, or bias.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the project team at contact@kiskolabs.com. All complaints will be reviewed and investigated promptly and fairly.

data/CONTRIBUTING.md

@@ -0,0 +1,84 @@
+# Contributing to Polyrun
+
+## Development setup
+
+```bash
+bundle install
+bundle exec appraisal install
+```
+
+## Tests
+
+```bash
+bundle exec rspec
+# or
+bundle exec rake spec
+```
+
+Coverage merge performance (large synthetic payloads):
+
+```bash
+bundle exec rake bench_merge
+# or: ruby benchmark/merge_coverage.rb
+```
+
+Run the suite under alternate Ruby constraints (see `Appraisals` and `gemfiles/`):
+
+```bash
+bundle exec appraisal ruby32 rspec
+bundle exec appraisal ruby34 rspec
+```
+
+## Linting
+
+[RuboCop](https://rubocop.org/) with [Standard](https://github.com/standardrb/standard) style, plus `rubocop-rspec` and `rubocop-thread_safety`. Project-specific cop tweaks and metric `Exclude` lists live in `.rubocop.yml`.
+
+```bash
+bundle exec rubocop
+bundle exec rubocop -a   # safe autocorrect
+bundle exec rake rubocop
+```
+
+## RBS
+
+Type signatures live under `sig/` and ship with the gem. Validate them after changes:
+
+```bash
+bundle exec rake rbs
+# equivalent: bundle exec rbs -I sig validate
+```
+
+Keep `require "polyrun"` free of RSpec/Minitest: optional wiring stays in `polyrun/rspec`, `polyrun/minitest`, and `polyrun/reporting/rspec_junit` (see README).
+
+[Trunk](https://trunk.io/) aggregates RuboCop, YAML, Markdown, shellcheck, and more (see `.trunk/trunk.yaml`):
+
+```bash
+trunk check
+trunk fmt
+```
+
+CI runs `rake ci` (RSpec + RuboCop). Optional Trunk workflow: `.github/workflows/trunk.yml`.
+
+## Adopting Polyrun in other repos
+
+- [docs/SETUP_PROFILE.md](docs/SETUP_PROFILE.md) — agent or human checklist (CI model A vs B, database, prepare).
+- `bundle exec polyrun init --list` — lists starter `polyrun.yml` and `POLYRUN.md` templates (see `examples/templates/README.md`).
+
+## Examples
+
+Runnable demos live under `examples/`. After changing the gem, smoke them:
+
+```bash
+cd examples && ./bin/ci_prepare
+cd examples/simple/simple_demo && RAILS_ENV=test bundle exec rspec
+# optional: complex polyrepo demo (multi-DB + three Vite clients + RSpec E2E)
+# cd examples/complex/polyrepo_demo && RAILS_ENV=test bin/rails db:prepare && bundle exec rspec
+```
+
+See `examples/README.md`.
+
+## Pull requests
+
+- One logical change per PR when possible.
+- Add or update specs for behavior changes.
+- Run `bundle exec rake ci` before pushing.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Andrei Makarov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,140 @@
+# Polyrun
+
+Ruby gem for parallel test runs, merged coverage (SimpleCov-compatible JSON to JSON, LCOV, Cobertura, or console output), CI reporting (JUnit, timing), and parallel-test hygiene (fixtures, snapshots, per-shard databases, asset preparation). Ship it as one development dependency: no runtime gem dependencies beyond the standard library and vendored code.
+
+## Why?
+
+Running tests in parallel across processes still requires a single merged coverage report, stable shard assignment, isolated databases per worker so rows are not shared, and reliable timing data for cost-based splits—without wiring together many small tools and shell scripts.
+
+Polyrun provides:
+
+- Orchestration: `plan`, `run-shards`, and `parallel-rspec` (run-shards plus merge-coverage), with an optional on-disk queue and constraints for file lists and load balancing.
+- Coverage: merge SimpleCov-compatible JSON fragments; emit JSON, LCOV, Cobertura, or console summaries (you can drop separate SimpleCov merge plugins for this path).
+- CI reporting: JUnit XML from RSpec JSON; slow-file reports from merged timing JSON.
+- Parallel hygiene: asset digest markers, SQL snapshots, YAML fixture batches, and DB URL or shard helpers aligned with `POLYRUN_SHARD_*`.
+- Optional **`polyrun quick`**: `Polyrun::Quick` — nested `describe`, `it` / `test`, `before` / `after`, `let` / `let!`, `expect(x).to …` matchers, `assert_*` (Minitest-like), and optional **`Polyrun::Quick.capybara!`** (extends `Capybara::DSL` when the **capybara** gem is loaded). Stdlib-only in Polyrun itself. Coverage uses the same `Polyrun::Coverage::Collector` path as RSpec when `POLYRUN_COVERAGE=1` or `config/polyrun_coverage.yml` is present (not when `POLYRUN_COVERAGE_DISABLE=1`).
+- No runtime gems in the gemspec: stdlib and vendored pieces only.
+
+Capybara and Playwright stay in your application; Polyrun does not replace browser drivers.
+
+## How?
+
+1. Add the gem (path or RubyGems) and `require "polyrun"` where you integrate—for example coverage merge in CI or prepare hooks.
+2. Add a `polyrun.yml` beside the app, or pass `-c` to point at one. Configure `partition` (paths, shard index and total, strategy), and optionally `databases` (Postgres template and `shard_db_pattern`), `prepare`, and `coverage`. If you use `partition.paths_build`, Polyrun can write `partition.paths_file` (for example `spec/spec_paths.txt`) from globs and ordered stages—substring priorities for integration specs, or a regex stage for “Rails-heavy files first”—without a per-project Ruby script. That step runs before `plan` and `run-shards`. Use `bin/polyrun build-paths` to refresh the paths file only.
+3. Run prepare once before fan-out—for example `script/ci_prepare` for Vite or webpack builds, and `Polyrun::Prepare::Assets` digest markers. See `examples/TESTING_REQUIREMENTS.md`.
+4. Run workers with `bin/polyrun run-shards --workers N -- bundle exec rspec`: N separate OS processes, each running RSpec with its own file list from `partition.paths_file`, or `spec/spec_paths.txt`, or else `spec/**/*_spec.rb`. Stderr shows where paths came from; after a successful multi-worker run it reminds you to run merge-coverage unless you use `parallel-rspec` or `run-shards --merge-coverage`.
+5. Merge artifacts with `bin/polyrun merge-coverage` on `coverage/polyrun-fragment-*.json` (one fragment per `POLYRUN_SHARD_INDEX` when coverage is on), or use `bin/polyrun parallel-rspec` or `run-shards --merge-coverage` so Polyrun runs merge for you. Optional: `merge-timing`, `report-timing`, `report-junit`.
+
+Quick CLI samples:
+
+If the current directory already has `polyrun.yml` or `config/polyrun.yml`, you can omit `-c` (same as `Config.load` default discovery). Pass `-c PATH` or set `POLYRUN_CONFIG` when the file lives elsewhere or uses another name.
+
+```bash
+bin/polyrun version
+bin/polyrun build-paths   # write spec/spec_paths.txt from partition.paths_build (uses polyrun.yml in cwd)
+bin/polyrun parallel-rspec --workers 5   # run-shards + merge-coverage (default: bundle exec rspec)
+bin/polyrun run-shards --workers 5 --merge-coverage -- bundle exec rspec
+bin/polyrun merge-coverage -i cov1.json -i cov2.json -o merged.json --format json,lcov,cobertura,console
+bin/polyrun env --shard 0 --total 4   # print DATABASE_URL exports from polyrun.yml in cwd
+bin/polyrun init --list
+bin/polyrun init --profile gem -o polyrun.yml   # starter YAML; see docs/SETUP_PROFILE.md
+bin/polyrun quick   # Polyrun::Quick examples under spec/polyrun_quick/ or test/polyrun_quick/
+```
+
+### Adopting Polyrun (setup profile and scaffolds)
+
+- [docs/SETUP_PROFILE.md](docs/SETUP_PROFILE.md) — Checklist for project type (gem, Rails, Appraisal), parallelism target (one CI job with N workers, matrix shards, or a single non-matrix runner), database layout, prepare, spec order, coverage, and CI model A (single runner with `parallel-rspec`) versus model B (matrix plus a merge-coverage job). Treat `polyrun.yml` as the contract; bin scripts and `database.yml` are adapters.
+- `polyrun init` writes a starter `polyrun.yml` or `POLYRUN.md` from built-in templates (`--profile gem`, `rails`, `ci-matrix`, `doc`). Profiles are listed in `examples/templates/README.md`.
+
+Runnable Rails demos (multi-DB, Vite, Capybara, Docker, Postgres sketches) live in `examples/README.md`. For development (tests, RuboCop, Appraisal), see [CONTRIBUTING.md](CONTRIBUTING.md).
+
+---
+
+## Library (after `require "polyrun"`)
+
+That single require loads the CLI and core library **without** loading RSpec or Minitest. Optional integrations (use only what your app needs):
+
+- `require "polyrun/rspec"` — `Polyrun::RSpec` registers `ParallelProvisioning` in `before(:suite)` (your app must use RSpec).
+- `require "polyrun/minitest"` — `Polyrun::Minitest` is a thin alias for `ParallelProvisioning.run_suite_hooks!` (does not `require "minitest"`).
+- `require "polyrun/reporting/rspec_junit"` — `Polyrun::Reporting::RspecJunit` adds RSpec’s JSON formatter and writes JUnit on exit; RSpec is loaded only inside `RspecJunit.install!`.
+
+| API | Purpose |
+|-----|---------|
+| `Polyrun::Quick` (`require "polyrun/quick"`) | Nested `describe`; `it` / `test`; `before` / `after`; `let` / `let!`; `expect(x).to eq` / `be_truthy` / `be_falsey` / `match` / `include`; `assert_*`. Call `Polyrun::Quick.capybara!` after `require "capybara"` (and configure `Capybara.app` in your app) to use `visit`, `page`, etc. Run: `polyrun quick` (defaults: `spec/polyrun_quick/**/*.rb`, `test/polyrun_quick/**/*.rb`). |
+| `Polyrun::Log` | Swappable stderr/stdout for all CLI and library messages. Set `Polyrun.stderr` / `Polyrun.stdout` (or `Polyrun::Log.stderr` / `stdout`) to an `IO`, `StringIO`, or Ruby `Logger`. `Polyrun::Log.reset_io!` clears custom sinks. |
+| `Polyrun::Coverage::Merge` | Merge fragments; formatters for JSON, LCOV, Cobertura, console summary. |
+| `Polyrun::Coverage::Collector` | Stdlib `Coverage` → JSON fragment (`POLYRUN_COVERAGE_DISABLE` to skip); `track_under: %w[lib app]`, filters, optional % gate. |
+| `Polyrun::Coverage::Reporting` | Write all formats to a directory from a blob or merged JSON file. |
+| `Polyrun::Reporting::JUnit` | RSpec `--format json` output or Polyrun testcase JSON → JUnit XML (CI). For RSpec formatter wiring see `Polyrun::Reporting::RspecJunit` (`require "polyrun/reporting/rspec_junit"`). |
+| `Polyrun::Timing::Summary` | Text report of slowest files from merged `polyrun_timing.json`. |
+| `Polyrun::Data::Fixtures` | YAML table batches (`each_table`, `load_directory`, optional `apply_insert_all!` with ActiveRecord). |
+| `Polyrun::Data::CachedFixtures` | Process-local memoized fixture blocks (`register` / `fetch`, stats, `reset!`). |
+| `Polyrun::Data::ParallelProvisioning` | Serial vs parallel-worker suite hooks from `POLYRUN_SHARD_*` / `TEST_ENV_NUMBER`. |
+| `Polyrun::Data::FactoryInstrumentation` | Opt-in FactoryBot patch → `FactoryCounts` (after `require "factory_bot"`). |
+| `Polyrun::Data::SqlSnapshot` | PostgreSQL `pg_dump` / `psql` snapshots under `spec/fixtures/sql_snapshots/`. |
+| `Polyrun::Data::FactoryCounts` | Factory/build counters + summary text. |
+| `Polyrun::RSpec` (`require "polyrun/rspec"`) | `install_parallel_provisioning!` → `before(:suite)` hooks. |
+| `Polyrun::Minitest` (`require "polyrun/minitest"`) | `install_parallel_provisioning!` → same as `ParallelProvisioning.run_suite_hooks!` (no Minitest gem dependency). |
+| `Polyrun::Reporting::RspecJunit` (`require "polyrun/reporting/rspec_junit"`) | CI: RSpec JSON formatter + JUnit from `install!` (RSpec loaded only there). |
+| `Polyrun::Prepare::Assets` | Digest trees, marker file, `assets:precompile`. |
+| `Polyrun::Database::Shard` | Shard env map, `%{shard}` DB names, URL path suffix for `postgres://`, `mysql2://`, `mongodb://`, etc. |
+| `Polyrun::Database::UrlBuilder` | URLs from `polyrun.yml` `databases:` — nested blocks or `adapter:` for common Rails stacks (`postgresql`, `mysql`/`mysql2`, `trilogy`, `sqlserver`/`mssql`, `sqlite3`/`sqlite`, `mongodb`/`mongo`). |
+
+## Development
+
+```bash
+bundle install
+bundle exec rake spec
+bundle exec rake rbs   # optional: validate RBS in sig/
+bundle exec rake ci   # RSpec + RuboCop
+```
+
+Tests include subprocess CLI coverage (`spec/polyrun/cli_spec.rb`: merge-coverage across formats, merge-timing, report-junit, report-timing, plan, env with `databases:`, prepare, report-coverage, db:* dry-run and errors) and unit specs for `Coverage::Merge`, `Timing::Merge`, `Timing::Summary`, `Reporting::JUnit`, `Partition::Plan`, `Database::UrlBuilder` and `Shard`, `Prepare::Artifacts`, `Data::*`, `Env::Ci`, `Queue::FileStore`, and `SqlSnapshot` (with `Open3` stubbed for `pg_dump`).
+
+Merge performance defaults align with `spec/polyrun/coverage/merge_scale_spec.rb` (~110 files × 310 lines per fragment):
+
+```bash
+ruby benchmark/merge_coverage.rb
+bundle exec rake bench_merge
+# MERGE_FRAGMENTS=16 MERGE_REPS=2 ruby benchmark/merge_coverage.rb
+```
+
+The script benchmarks `merge_two`, balanced `merge_blob_tree` (same reduction as `merge-coverage` / `merge_files`), a naive left-fold, JSON on disk via `merge_files`, and `merge_fragments` with `meta` and `polyrun_coverage_groups` (group recomputation).
+
+Merge is JSON aggregation over coverage fragments; for typical apps it stays well under one second. If merge exceeds ten seconds, Polyrun prints a warning on stderr (override with `POLYRUN_MERGE_SLOW_WARN_SECONDS`; set to `0` to disable).
+
+## CLI (reference)
+
+```bash
+bin/polyrun plan --total 2 --shard 0 a.rb b.rb c.rb
+bin/polyrun plan --total 3 --shard 0 --timing polyrun_timing.json --paths-file spec/spec_paths.txt
+bin/polyrun plan --strategy hrw --total 4 --shard 0 --paths-file spec/spec_paths.txt
+bin/polyrun queue init --paths-file spec/spec_paths.txt --timing polyrun_timing.json --dir .polyrun-queue
+bin/polyrun report-coverage -i merged.json -o coverage/out --format json,lcov,cobertura,console
+bin/polyrun report-junit -i rspec.json -o junit.xml
+bin/polyrun report-timing -i polyrun_timing.json --top 20
+bin/polyrun plan --shard 0 --total 4   # polyrun.yml in cwd
+bin/polyrun prepare --recipe assets --dry-run
+bin/polyrun parallel-rspec --workers 4
+bin/polyrun quick spec/polyrun_quick/smoke.rb
+```
+
+`polyrun.yml` can set `partition.*`, `prepare.recipe` (`default` or `assets`), `prepare.rails_root`, and related keys. `POLYRUN_SHARD_*` overrides configuration where documented; CLI flags override environment variables.
+
+Shard index and total in CI (`Polyrun::Env::Ci`): when set, `POLYRUN_SHARD_INDEX` and `POLYRUN_SHARD_TOTAL` take precedence. When `CI` is truthy, `CI_NODE_INDEX` / `CI_NODE_TOTAL` and other parallel-job environment variables are read if present. If your runner does not export those, set `POLYRUN_SHARD_*` from the job matrix.
+
+File queue (`polyrun queue …`): batches live on disk under a lock file; paths move from `pending` to `leases` on claim and to `done` on ack. There is no lease TTL: if a worker dies after claiming, paths remain in `leases` until you recover them (manually or with a future reclaim command).
+
+## Examples
+
+See [`examples/README.md`](examples/README.md) for Rails apps (Capybara, Playwright, Vite, multi-database, Docker Compose, polyrepo). Parallel CI practices: [`examples/TESTING_REQUIREMENTS.md`](examples/TESTING_REQUIREMENTS.md). Behavioral contracts: `spec/polyrun/mandatory_parallel_support_spec.rb`.
+
+You can replace SimpleCov and simplecov plugins, parallel_tests, and rspec_junit_formatter with Polyrun for those roles. Use `merge-timing`, `report-timing`, and `Data::FactoryCounts` (optionally with `Data::FactoryInstrumentation`) for slow-file and factory metrics. YAML fixture batches and bulk inserts can use `Data::Fixtures` and `ParallelProvisioning` for shard-aware seeding; wire your own `truncate` and `load_seed` in hooks.
+
+---
+
+Sponsored by [Kisko Labs](https://www.kiskolabs.com).
+
+<a href="https://www.kiskolabs.com">
+  <img src="kisko.svg" width="200" alt="Sponsored by Kisko Labs" />
+</a>

data/SECURITY.md

@@ -0,0 +1,27 @@
+# SECURITY
+
+## Reporting a Vulnerability
+
+Do not open a public GitHub issue for security vulnerabilities.
+
+Email security details to security@kiskolabs.com.
+
+Include: description, steps to reproduce, potential impact, and suggested fix (if available).
+
+### Response Timeline
+
+- We will acknowledge receipt of your report
+- We will provide an initial assessment
+- We will keep you informed of our progress and resolution timeline
+
+### Disclosure Policy
+
+- We will work with you to understand and resolve the issue
+- We will credit you for the discovery (unless you prefer to remain anonymous)
+- We will publish a security advisory after the vulnerability is patched
+- We will coordinate public disclosure with you
+
+## Automation security
+
+- Context isolation: do not include production credentials, API keys, or personally identifiable information in prompts sent to third-party LLMs or automation services.
+- Supply chain: verify automated dependencies.

data/bin/polyrun

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+$LOAD_PATH.unshift File.expand_path("../lib", __dir__)
+require "polyrun"
+
+status = Polyrun::CLI.run(ARGV)
+exit(status.nil? ? 0 : status)

data/docs/SETUP_PROFILE.md

@@ -0,0 +1,106 @@
+# Polyrun setup profile (agent / human checklist)
+
+Use this as a fill-in worksheet before editing a host project. `polyrun.yml` is the contract; everything else is an adapter that must stay aligned with it.
+
+## 1. Project shape
+
+| Field | Options / notes |
+|--------|------------------|
+| Project type | Gem (library, no Rails app), Rails (full app), or multi-gemfile (Appraisal / multiple `gemfiles/*.gemfile`) |
+| Gemfile path to polyrun | For example `gem "polyrun", path: "../polyrun.rb"` or `gem "polyrun"` from RubyGems—note the path relative to each gemfile |
+| Appraisal / Docker | If Appraisal: polyrun must appear in `Appraisals` and each generated gemfile. If Docker: document working directory and whether prepare is one-shot or repeated with tests |
+
+## 2. Parallelism target (pick one primary story)
+
+| Target | Typical CLI / CI |
+|--------|-------------------|
+| Single CI job, N workers on one runner | One workflow job runs `polyrun parallel-rspec --workers N` (or `start`); merge coverage in the same job or a small follow-up step; upload artifacts |
+| Matrix: one shard per CI job | Matrix sets `POLYRUN_SHARD_INDEX` / `POLYRUN_SHARD_TOTAL` (or CI vendor equivalents—see `Polyrun::Env::Ci` and the README); each job runs `plan` plus the test command for its shard; upload `coverage/polyrun-fragment-<i>.json`; a merge job runs `merge-coverage` |
+
+Do not mix “fan out N workers inside one job” with “matrix shard index” in the same workflow without a clear story for which process writes which fragment and where merge runs.
+
+## 3. Database
+
+| Field | Options |
+|--------|---------|
+| Single test DB | Omitting `databases:` in `polyrun.yml` may be enough; ensure parallel workers do not share one DB if they mutate data |
+| Multi-DB or shard suffixes | `databases:` in `polyrun.yml` (`shard_db_pattern`, `template_db`, optional `connections` and `env_key`). `database.yml` or `DATABASE_URL` may use `%{shard}` or `POLYRUN_SHARD_INDEX` suffixes—the same convention as `polyrun env` |
+| External provisioning | Sometimes `db:prepare` plus shell clone scripts (multi-DB apps)—document ordering: prepare databases before `run-shards` |
+
+## 4. Prepare (run once before workers)
+
+| Field | Options |
+|--------|---------|
+| None | Typical for gems without assets |
+| Assets | `Polyrun::Prepare::Assets`, `prepare.recipe: assets` or `default`, digest markers |
+| Playwright / browsers | Install once in prepare; workers skip reinstall (`SKIP_*` env flags in app code if needed) |
+| Custom shell | `prepare.recipe: shell` with `prepare.command:`—must not repeat heavy work inside each worker |
+
+Rule: anything expensive (compile, `yarn`, Playwright download) belongs in prepare or a CI cache step, not in `before(:suite)` per worker unless gated by `POLYRUN_SHARD_TOTAL` or similar env.
+
+## 5. Spec list and ordering
+
+| Field | Options |
+|--------|---------|
+| Plain glob | `partition.paths_build.all_glob: spec/**/*_spec.rb` and empty or minimal `stages` |
+| Ordered stages | `partition.paths_build.stages`: regex (e.g. slow integration first) or `sort_by_substring_order` for stable ordering |
+
+Refresh list: `polyrun -c polyrun.yml build-paths` (also runs automatically before `plan` / `run-shards` when configured).
+
+## 6. Coverage and CI reports
+
+| Field | Options |
+|--------|---------|
+| Collector | `require "polyrun"` plus `Polyrun::Coverage::Collector.start!` in `spec_helper` (non-Rails gems) |
+| Rails | `require "polyrun/coverage/rails"` (or documented Rails integration) in `spec_helper` / `test_helper` |
+| Fragments | Per shard: `coverage/polyrun-fragment-<shard>.json` |
+| Merge | `polyrun merge-coverage` on fragments → merged JSON; then `polyrun report-coverage` (formats: json, lcov, cobertura, console, html, …) |
+| JUnit | `polyrun report-junit` from RSpec JSON if needed |
+
+## 7. `polyrun.yml` as contract — adapters
+
+After `polyrun.yml` is fixed, add or adjust adapters (same shard semantics):
+
+| Adapter | Role |
+|---------|------|
+| `bin/rspec_parallel` / `bin/rspec_ci_shard` | Thin wrappers: prepare, start, or plan + rspec |
+| `bin/polyrun-rspec` | Single shard (`env` + plan + rspec), e.g. one matrix cell or ad-hoc run |
+| `config/database.yml` | ERB / suffixes matching `databases.shard_db_pattern` |
+| Prepare script | Referenced from `prepare.command` |
+| `POLYRUN.md` (or `spec/README`) | Canonical commands for this repo; CI model (below) |
+
+Bot workflow: read and write `polyrun.yml` first, then generate or patch wrappers and docs to match.
+
+## 8. CI models (document one in `POLYRUN.md`)
+
+Model A — one job, N worker processes
+
+- Command: `polyrun -c polyrun.yml parallel-rspec --workers N` (or `polyrun start`). Global `-c` / `-v` / `-h` must appear before the subcommand.
+- Coverage fragments appear on the same runner; `merge-coverage` can run in the same job after workers finish.
+
+Model B — matrix of jobs (one shard per job)
+
+- Each job sets `POLYRUN_SHARD_INDEX` / `POLYRUN_SHARD_TOTAL` (and DB URLs per shard if needed).
+- Run `polyrun build-paths`, `polyrun plan`, then `bundle exec rspec` (or `bin/rspec_ci_shard`) for that shard only.
+- Upload `coverage/polyrun-fragment-*.json` (or named per shard).
+- A final `merge-coverage` job downloads artifacts and merges.
+
+GitHub Actions does not set `CI_NODE_INDEX` / `CI_NODE_TOTAL` by default—set `POLYRUN_*` explicitly in the matrix.
+
+## 9. Chatbot / agent context blocks (high signal)
+
+1. Upstream README sections: partition, prepare, databases, merge-coverage, `Env::Ci` (shard detection).
+2. Project `polyrun.yml` (filled in) plus one of: `POLYRUN.md` or `spec/README.md` with the canonical test command and CI model (A or B).
+3. Exact `Gemfile` / Appraisal lines for `polyrun` and any Docker or path notes.
+
+## 10. Scaffold from this repo
+
+```bash
+polyrun init --list
+polyrun init --profile gem -o polyrun.yml
+polyrun init --profile rails -o polyrun.yml
+polyrun init --profile ci-matrix -o polyrun.yml
+polyrun init --profile doc -o POLYRUN.md    # host-project doc template
+```
+
+Templates live under `lib/polyrun/templates/` in the gem. See `examples/templates/README.md` for profile descriptions.

data/lib/polyrun/cli/coverage_commands.rb

@@ -0,0 +1,150 @@
+require "json"
+require "fileutils"
+require "optparse"
+
+require_relative "coverage_merge_io"
+
+module Polyrun
+  class CLI
+    module CoverageCommands
+      include CoverageMergeIo
+
+      private
+
+      def cmd_merge_coverage(argv, _config_path)
+        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)"
+          return 2
+        end
+
+        Polyrun::Log.warn "merge-coverage: merging #{inputs.size} fragment(s)" if @verbose
+        Polyrun::Debug.log_kv(
+          merge_coverage: "start",
+          output: output,
+          formats: formats,
+          input_paths: inputs
+        )
+        input_bytes = inputs.sum { |p| File.size(p) }
+        Polyrun::Debug.log("merge-coverage: input_bytes=#{input_bytes}")
+
+        t0 = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        r = merge_coverage_merge_fragments(inputs)
+        merged = r[:blob]
+        Polyrun::Debug.log("merge-coverage: merged_blob file_count=#{merged.size}")
+
+        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)
+
+        elapsed = Process.clock_gettime(Process::CLOCK_MONOTONIC) - t0
+        merge_coverage_log_finish(elapsed, inputs)
+        0
+      end
+
+      # Warn when wall time exceeds this many seconds (default 10). Set POLYRUN_MERGE_SLOW_WARN_SECONDS=0 to disable.
+      def merge_slow_warn_threshold_seconds
+        v = ENV["POLYRUN_MERGE_SLOW_WARN_SECONDS"]
+        return 10.0 if v.nil? || v.to_s.strip.empty?
+
+        s = v.to_s.strip.downcase
+        return nil if %w[0 false no].include?(s)
+
+        Float(v)
+      rescue ArgumentError
+        10.0
+      end
+
+      def cmd_report_coverage(argv)
+        input = nil
+        output_dir = "coverage/polyrun"
+        basename = "polyrun-coverage"
+        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.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 }
+          opts.on("--format LIST", String) { |v| formats = v.split(",").map(&:strip) }
+        end
+        parser.parse!(argv)
+        input ||= argv.first
+
+        unless input && File.file?(input)
+          Polyrun::Log.warn "report-coverage: need -i FILE or a path argument"
+          return 2
+        end
+
+        paths = Polyrun::Debug.time("report-coverage: write_from_json_file") do
+          Polyrun::Coverage::Reporting.write_from_json_file(
+            File.expand_path(input),
+            output_dir: File.expand_path(output_dir),
+            basename: basename,
+            formats: formats
+          )
+        end
+        Polyrun::Log.puts JSON.generate(paths.transform_keys(&:to_s))
+        0
+      end
+
+      def merge_coverage_after_shards(output:, format_list:, config_path:)
+        files = merge_coverage_fragment_json_files
+        if files.empty?
+          Polyrun::Log.warn "polyrun run-shards: --merge-coverage: no coverage/polyrun-fragment-*.json found (enable Polyrun coverage in spec_helper?)"
+          return 0
+        end
+
+        merge_coverage_after_shards_log_start(files, output, format_list)
+        code = merge_coverage_after_shards_run_merge(files, output, format_list, config_path)
+        return code unless code == 0
+
+        merge_coverage_after_shards_strict_gate(output, code)
+      rescue JSON::ParserError => e
+        Polyrun::Log.warn "polyrun run-shards: merged coverage JSON parse failed: #{e.message}"
+        1
+      end
+
+      def merge_coverage_fragment_json_files
+        pattern = File.join(Dir.pwd, "coverage", "polyrun-fragment-*.json")
+        Dir.glob(pattern).sort
+      end
+
+      def merge_coverage_after_shards_log_start(files, output, format_list)
+        Polyrun::Log.warn "polyrun run-shards: merging #{files.size} coverage fragment(s) → #{output}"
+        Polyrun::Debug.log("merge-coverage-after-shards: #{files.size} fragment(s) → #{output} format=#{format_list}")
+        Polyrun::Debug.log("merge-coverage-after-shards: fragments=#{files.join(", ")}")
+      end
+
+      def merge_coverage_after_shards_run_merge(files, output, format_list, config_path)
+        merge_argv = []
+        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)
+        end
+      end
+
+      def merge_coverage_after_shards_strict_gate(output, code)
+        gate = coverage_minimum_line_gate_from_polyrun_coverage_yml
+        Polyrun::Debug.log_kv(
+          coverage_gate_config: "polyrun_coverage.yml",
+          gate: gate.inspect
+        )
+        return code if gate.nil? || !gate[:strict]
+
+        merged_path = File.expand_path(output)
+        unless File.file?(merged_path)
+          Polyrun::Log.warn "polyrun run-shards: --merge-coverage: expected merged JSON at #{merged_path} missing"
+          return 1
+        end
+
+        below = merge_coverage_min_line_gate_below?(merged_path, gate)
+        return 1 if below
+
+        code
+      end
+    end
+  end
+end