moots 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 49077c78f2418214b2e331c9540b4e2f69e365d4bd4107fcd48373eac16395f0
+  data.tar.gz: f0be889f311faa2edbb112eb229070adde1667710329901b0cb4f2c9878c9b71
+SHA512:
+  metadata.gz: ca28e8c3afc830bb851ef12fe75f8f84cb55ea8e85a46fed48b21576d279dbc97be00a618c4849229e74912e938ba29d430330893845bfa71d9a85032107fd19
+  data.tar.gz: dfa2cd560720aa7432b772a8c121b0314a2b1e2191b11db7dc4c7f77bc3d283d4c96d785a8125b4afe8602638bb1e16ebcb875d780534dd958fc0997be855807

data/CHANGELOG.md

@@ -0,0 +1,34 @@
+# Changelog
+
+## 0.1.0 - 2026-10-29
+
+- Add optional parallel execution with `--jobs N` or YAML/API `jobs`, keeping one
+  worker as the default. Each worker receives a copy of the verified baseline;
+  errors and interruption cancel active commands and clean up all copies.
+- Preserve source order in parallel API/JSON results, including partial errors,
+  while serializing live progress callbacks on the calling thread. Check the
+  independent RSpec/Minitest corpus with both one and two workers.
+- Run baselines and mutations in isolated copies by default, preserving uncommitted
+  project files and original report paths/IDs. Add configurable copy exclusions,
+  Bundler path rebasing and an explicit `isolation: false` compatibility mode.
+- Verify cleanup and original-source protection, including forced termination;
+  reject linked paths, special files and source globs that escape the snapshot.
+- Stream baseline and mutation progress, with IDs, survivor expression diffs and
+  rerun arguments; select one mutation using `--mutation ID` or YAML.
+- Add versioned JSON reports (`--format json`) with separate progress output,
+  captured test output and explicit partial-error reports. Interruptions exit 130.
+- Add optional Ruby API progress callbacks and declare the JSON runtime dependency.
+- Mutate equality (`==`, `!=`) and strict/inclusive boundaries (`>`, `>=`, `<`, `<=`).
+- Add an independent comparison acceptance corpus for RSpec and Minitest, checking
+  exact kills and survivors against strong and deliberately weak test suites.
+- Support maintained CRuby 3.3, 3.4 and 4.0; raise the minimum from 3.1 to 3.3.
+- Replace the runtime parser dependency with Prism and remove OpenStruct.
+- Refresh dependencies and add cross-platform CI, coverage and self-mutation gates.
+- Add the documented `moots` executable and validated, safe YAML configuration.
+- Replace exactly one operator by byte location, preserving repeated expressions,
+  multiline source, encodings, comments and line endings.
+- Support keyword boolean operators and explicit arithmetic operator calls.
+- Require a passing baseline and restore original source even after execution errors.
+- Add command deadlines, output capture and process cleanup; distinguish operational
+  errors from killed mutations and fail empty mutation runs.
+- Expand unit and subprocess integration tests with full runtime line/branch coverage.

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,132 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall
+  community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances of
+  any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email address,
+  without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official email address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+[INSERT CONTACT METHOD].
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of
+actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or permanent
+ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior, harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the
+community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+Community Impact Guidelines were inspired by
+[Mozilla's code of conduct enforcement ladder][Mozilla CoC].
+
+For answers to common questions about this code of conduct, see the FAQ at
+[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at
+[https://www.contributor-covenant.org/translations][translations].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[Mozilla CoC]: https://github.com/mozilla/diversity
+[FAQ]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Dave Russell
+
+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,312 @@
+# Moots
+
+Moots is a small, MIT-licensed mutation testing tool for Ruby. It changes one
+operator in your source, runs your tests in a fresh process, and reports whether
+the tests caught the change.
+
+A **killed** mutation made the tests fail. A **surviving** mutation left them
+passing and is worth investigating: it may reveal a missing assertion, untested
+behavior, or an equivalent change.
+
+Moots is still an early project with a deliberately small set of mutation
+operators. A perfect score measures those operators; it does not prove that a
+program is correct.
+
+## Ruby support
+
+Supports CRuby **3.3, 3.4 and 4.0**, with a minimum of Ruby 3.3. These are the
+[maintained Ruby series](https://www.ruby-lang.org/en/downloads/branches/).
+CI runs all three on Linux and Ruby 4.0 on Windows and macOS.
+
+Parsing uses [Prism](https://github.com/ruby/prism), including modern Ruby syntax.
+The old `parser` gem only handles syntax through Ruby 3.3. Runtime dependencies
+are Prism and JSON; development tools are kept in the Gemfile.
+
+## Installation
+
+Add Moots to your test/development bundle:
+
+```ruby
+group :development, :test do
+  gem "moots"
+end
+```
+
+To use a development checkout instead, add
+`gem "moots", path: "/path/to/moots"` to the project Gemfile, or run
+`bundle exec rake install` in this repository. Then run `bundle install`.
+
+Windows installations need RubyInstaller's MSYS2 development toolchain to build
+Prism and development dependencies (`ridk install`). This repository can also be
+developed under WSL with a supported Linux Ruby.
+
+## Usage
+
+From the project root:
+
+```sh
+bundle exec moots
+bundle exec moots --config config/moots.yml
+bundle exec moots --format json > moots-report.json
+bundle exec moots --mutation MUTATION_ID
+bundle exec moots --jobs 2
+bundle exec moots --help
+```
+
+Moots reads `.moots.yml` when present. Without it, the defaults below apply:
+
+```yaml
+include:
+  - app/**/*.rb
+  - lib/**/*.rb
+exclude: []
+test_command: bundle exec rspec
+timeout: 60
+mutation: null
+isolation: true
+jobs: 1
+workspace_exclude: [tmp, coverage, pkg, .rspec_status]
+```
+
+Paths are relative to the current working directory, including when using an
+explicit configuration path. Overlapping include patterns are deduplicated;
+exclude patterns take precedence. Unknown options, malformed YAML and invalid
+option values are errors.
+
+`test_command` can also be an argument array, which passes arguments literally
+without shell interpretation:
+
+```yaml
+test_command: [bundle, exec, rspec, spec/models]
+```
+
+The command must run the relevant tests in a fresh process and reload changed
+source. Avoid persistent test preloaders such as Spring. A command that runs no
+tests can still exit successfully; make sure your test runner rejects empty
+suites when appropriate.
+
+Exit statuses:
+
+| Status | Meaning |
+| --- | --- |
+| 0 | At least one mutation, all killed (or help/version requested) |
+| 1 | Survivors, or no mutations generated |
+| 2 | Configuration, source, baseline or command execution error |
+| 130 | Interrupted run |
+
+## Progress, survivors and CI reports
+
+Text output starts before the baseline tests run, then shows `[current/total]`
+progress before each mutation's tests. Each result has an ID and a relative
+`file:line` location. Survivors include an expression diff (`-` original, `+`
+replacement) and a `Rerun argv` argument array. The diff covers the mutated
+expression; it is not a patch for the whole file.
+
+Use `--mutation ID` to run a reported mutation with a fresh baseline. It overrides
+the optional `mutation` YAML setting. IDs use the relative file path, byte offset
+and original/replacement bytes, so equivalent checkouts produce the same IDs.
+Source edits can change IDs. An unknown ID is an error; it never silently runs
+the full suite or reports success. Use the same working directory, configuration
+and source revision when reproducing a result.
+
+`--format json` writes one JSON document to stdout; progress and diagnostics go
+to stderr. Test-process output is captured inside the document. The schema is
+described in [docs/reporting.md](docs/reporting.md). It includes:
+
+- `schema_version: 1` and `status: "completed"` or `"error"`.
+- Summary counts and each completed mutation's ID, source location, expressions,
+  killed/survived status, captured test output and rerun arguments.
+- An `error` message on operational failure or interruption. Any partial results
+  cover only completed mutations; an aborted run is never marked completed.
+
+Completion does not mean all mutations were killed. Continue to check the exit
+status (or the summary) in CI. Invalid UTF-8 in report text is replaced with `�`;
+mutation identity and source restoration still use the original bytes.
+
+## Mutation behavior
+
+Supported replacements:
+
+| Original | Replacement |
+| --- | --- |
+| `+` | `-` |
+| `-` | `+` |
+| `*` | `/` |
+| `/` | `*` |
+| `==` | `!=` |
+| `!=` | `==` |
+| `>` | `>=` |
+| `>=` | `>` |
+| `<` | `<=` |
+| `<=` | `<` |
+| `&&` | `||` |
+| `||` | `&&` |
+| `and` | `or` |
+| `or` | `and` |
+
+Each mutation changes exactly one operator token, including explicit operator
+calls such as `a.+(b)`. Other operators on the same line, string contents,
+comments and surrounding formatting are preserved. Byte offsets handle
+multiline expressions, Unicode and CRLF files.
+
+Boundary mutations switch between strict and inclusive comparisons, exposing
+missing tests for the value exactly at a limit. Equality mutations invert the
+comparison. Explicit calls such as `a.>=(b)` are supported too.
+
+Compound assignments (`+=`, `&&=`, etc.), unary operators, other comparisons
+(`===`, `<=>`, `=~`, `!~`), constants and method removal are not currently mutated.
+Equivalent mutations are not automatically filtered.
+
+## Execution and isolation
+
+Moots copies the current project into a temporary directory and runs the baseline
+and mutations there. Uncommitted and untracked files are included; no Git commit
+is required. The original checkout is never used for mutation writes. Reported
+paths and mutation IDs still refer to that checkout.
+
+A failing baseline aborts before any mutations. Within the copy, files are
+processed sequentially and restored after each mutation, including errors and
+interruptions. Each run uses one copy, so test-generated artifacts persist
+between invocations within that run. The copy is removed when the run finishes
+or raises. Hard termination may leave an orphan copy, but mutation writes still
+cannot affect the original files.
+
+The `workspace_exclude` globs omit files or entire directories from the copy;
+they are separate from `exclude`, which only controls mutation targets. The
+default copy exclusions are `tmp`, `coverage`, `pkg` and `.rspec_status`. Supplying
+your own list replaces those defaults; use `[]` if your tests need everything.
+Git, Mercurial and Subversion metadata are always omitted, including nested
+repositories and worktree pointer files. Installed dependencies such as
+`vendor/bundle` are copied, so large projects may need more time and disk space.
+
+Links (including directory junctions), special files and source globs that escape
+the project are rejected in isolated mode. Exclude unnecessary linked paths with
+`workspace_exclude`. The system temporary directory must be outside the project.
+See [docs/isolation.md](docs/isolation.md) for path handling and compatibility.
+
+Source read/write failures and invalid Ruby syntax are reported as errors;
+they are not silently excluded from a score. Missing commands, shell execution
+failures (exit 126/127), signal termination and timeouts are also errors rather
+than successful kills. Other nonzero exits count as killed mutations.
+
+The timeout applies to each test invocation, including the baseline. Standard
+output and standard error are drained concurrently. On POSIX systems the runner
+kills the process group on interruption or timeout; on Windows it uses
+`taskkill /T /F` for the command's process tree.
+
+Isolation protects the checkout from Moots' mutation writes; it is not a security
+sandbox. Test commands can still access external files, services and databases.
+Avoid editing the project while the snapshot is being copied. Windows descendants
+whose parent has already exited may outlive tree cleanup.
+
+For projects that require their original location or Git metadata, explicitly
+set `isolation: false`. This restores the previous in-place behavior: use a
+disposable checkout and avoid concurrent edits or mutation jobs. An `ensure`
+block restores source bytes after normal failures, but cannot protect against
+hard termination, power loss or a failed restoration write.
+
+## Parallel execution
+
+`--jobs N` (or `jobs: N` in YAML/the Ruby API) runs up to N test commands at once.
+The default is `1`, preserving sequential execution. Parallel execution requires
+`isolation: true`; in-place concurrent mutations are rejected.
+
+Moots runs one baseline, then prepares an independent copy of that verified
+snapshot for each worker. Workers include any artifacts produced by the baseline,
+but never share mutated files. The worker count is capped at the number of
+selected mutations. Empty runs and single-mutation reruns avoid creating a pool.
+
+Start with `--jobs 2` and size the pool for your available CPU, memory and disk.
+Each worker needs a full project copy and may itself run a parallel test suite.
+Working copies do not isolate databases, network ports or external services;
+keep `jobs: 1` for suites that cannot safely run concurrently.
+
+Progress and completed-result messages can arrive out of order, with each
+mutation retaining its original index and ID. The returned Ruby array and final
+JSON results stay in source order. Progress callbacks execute serially on the
+calling thread. Operational errors, callback failures and interruptions stop
+the pool, terminate active test commands and clean up all working copies.
+Partial JSON error reports retain only completed results, in source order.
+
+## Ruby API
+
+```ruby
+require "moots"
+
+results = Moots.run(
+  include: ["lib/**/*.rb"],
+  exclude: ["lib/generated/**/*.rb"],
+  test_command: ["bundle", "exec", "rspec"],
+  timeout: 60
+)
+
+results.each do |result|
+  puts [result.mutation.file_path, result.mutation.line_number, result.killed].inspect
+  puts result.test_result.output
+end
+```
+
+`MutationGenerator#generate_mutations(code, file_path: "example.rb")` returns
+mutations with original/replacement expressions and a byte offset.
+`Mutation#apply(code)` returns a changed copy and rejects mismatched source.
+`Mutation#id` returns the rerunnable ID; `Mutation#relative_path` returns its
+project-relative path. Both accept an optional `root:` directory.
+Directly constructed mutations now require `start_offset:`.
+Invalid input raises `Moots::Error`; source I/O errors also propagate from the API.
+
+An optional block receives progress hashes while `Moots.run` still returns the
+results array. Events are `:workspace_started` (isolated runs only, before copying),
+`:baseline_started`, `:baseline_passed`,
+`:mutation_started` (with `:mutation`, one-based `:index`, and `:total`) and
+`:mutation_finished` (with `:result`, `:index`, and `:total`). Callbacks execute
+before source modification or after restoration, and callback exceptions propagate.
+After the baseline passes, Moots reads all selected source files to determine the
+mutation count before executing any mutations.
+
+## Development and verification
+
+```sh
+bundle install
+bundle exec rake spec       # randomized RSpec suite
+bundle exec rake acceptance # independent RSpec and Minitest comparison fixtures
+bundle exec rake coverage   # 100% line and branch coverage, overall and per file
+bundle exec rake rubocop
+bundle exec rake mutation   # run Moots against all lib/**/*.rb files
+bundle exec rake "mutation[2]" # dogfood with two isolated workers
+bundle exec rake verify     # lint, coverage, then dogfood
+bundle exec rake build
+```
+
+Coverage includes unloaded runtime files. Only `lib/moots/version.rb` is excluded,
+because Bundler loads its release constant before coverage starts; the version
+is checked separately. No runtime implementation file is excluded from
+self-mutation. The mutation task disables coverage thresholds in child suites
+so kills come from test failures rather than uncovered-line enforcement.
+This repository's `.moots.yml` uses RSpec's `--fail-fast`: the passing baseline
+still runs every example, while a mutant stops at its first failing assertion.
+
+Tests use temporary projects, real subprocesses and controlled failures. They
+exercise every supported operator, exact mutation locations, modern syntax,
+encodings, configuration and CLI behavior, baseline validation, process output,
+deadlines and byte-for-byte restoration. The integration suite proves that
+strong tests kill mutations, weak tests leave survivors, and broken baselines
+are rejected.
+
+The [comparison acceptance corpus](spec/fixtures/comparisons/README.md) uses a
+standalone subject with hand-written expected results, independent of Moots'
+operator tables. RSpec and Minitest each run strong and deliberately weak suites.
+The strong suites kill all six comparison mutations. The weak suites omit the
+exact boundary: equality mutations still die, but all four boundary mutations
+survive. These acceptance checks are also included in the normal spec suite.
+
+The self-mutation run must generate at least one mutation and kill every one.
+CI runs it with two workers on all supported Linux Ruby versions. Review surviving
+mutations and improve behavioral assertions; do not exclude implementation
+files just to get a green result.
+
+## Contributing and license
+
+Bug reports and pull requests are welcome at
+[OkayDave/moots](https://github.com/OkayDave/moots).
+Released under the [MIT License](LICENSE.txt).
+Contributors must follow the [Code of Conduct](CODE_OF_CONDUCT.md).

data/docs/isolation.md

@@ -0,0 +1,89 @@
+# Isolated working copies
+
+`isolation: true` is the default for both the CLI and `Moots.run`. The project
+root is the current working directory. Moots snapshots its current files, runs
+the baseline and every mutation in the snapshot, then removes it. This does not
+require Git and includes uncommitted changes and untracked files.
+
+Files are copied independently, never hardlinked to the checkout. File bytes
+and executable permissions are preserved. Hidden files and dependencies are
+included. `.git`, `.hg` and `.svn` entries are always omitted at every depth.
+Tests that need version-control metadata can use explicit in-place operation.
+
+## Copy exclusions
+
+```yaml
+isolation: true
+workspace_exclude:
+  - tmp
+  - coverage
+  - pkg
+  - .rspec_status
+  - node_modules
+```
+
+Patterns match project-relative paths, with `/` as the separator. `*`, `**`,
+brace alternatives and hidden names are supported. A matching directory omits
+its entire subtree. `cache` matches the root cache directory; `**/cache` matches
+cache directories at any depth. A custom list replaces the defaults. Use `[]`
+to copy all ordinary files, including default-excluded directories.
+
+`exclude` still only removes mutation targets. Tests, fixtures and support files
+usually need to be copied even when they are excluded from mutation.
+
+Links, directory junctions and special files are rejected with a diagnostic;
+Moots does not follow or preserve them into the snapshot. Copy exclusions are
+applied first, so unnecessary linked directories can be omitted explicitly.
+Read failures and insufficient disk space abort the run and remove partial copies.
+
+## Commands, Bundler and paths
+
+The parent process keeps its original working directory and environment. Each
+test subprocess starts in the snapshot. Relative paths therefore use the copied
+files. Absolute project-local paths supplied as separate `test_command` array
+arguments are rebased into the snapshot. External paths remain unchanged.
+Use separate arguments for path-bearing options, for example `[ruby, -I, lib,
+test.rb]`. Embedded paths such as `-I/checkout/lib` are not rewritten.
+
+Moots also rebases project-local entries in `BUNDLE_GEMFILE`, `BUNDLE_APP_CONFIG`,
+`BUNDLE_BIN_PATH`, `BUNDLE_PATH`, `GEM_HOME`, `GEM_PATH`, `RUBYLIB` and `PATH`,
+including Bundler's saved `BUNDLER_ORIG_` values. Dependencies under `vendor/bundle`
+are copied, preserving relative Bundler install paths. Dependencies outside the
+project continue to be shared.
+
+Shell command strings, Ruby snippets, `RUBYOPT`, configuration file contents and
+other environment variables are not rewritten. Prefer relative paths in those
+places. An absolute Bundler path or local gem override stored inside
+`.bundle/config` can still point to the original project. Configure those paths
+relatively, or use `isolation: false` when relocation is incompatible with the
+project. Ensure the test command actually reloads the copied source; persistent
+test preloaders are unsupported.
+
+Include/exclude source globs must stay inside the project in isolated mode.
+Results retain the original source paths and IDs; reported rerun commands should
+be executed from the original project directory with the same source and config.
+
+## Lifetime and limits
+
+With `jobs: 1`, one temporary directory is used for the whole run. With multiple
+workers, the baseline runs once and each worker receives an independent copy of
+that verified snapshot, including baseline-generated artifacts. Workers reuse
+their own copy across assigned mutants; no two workers mutate the same copy.
+Source bytes are restored between mutants, while other test-generated files can
+persist in that worker. Tests should reset their own state between invocations.
+
+Cleanup runs on success, failure, timeout and interruption. Active worker test
+commands are stopped before their directories are removed. Hard termination can
+leave `moots-workspace-*` or `moots-workers-*` directories in the system temporary
+directory. The original source bytes remain untouched by mutation writes even
+in that case. Parallel runs need extra disk space and do not isolate shared
+external resources such as databases, services and network ports.
+
+The temporary directory must be outside the project to prevent recursive copying.
+The snapshot is not atomic: avoid editing source while it is being copied.
+Isolation does not confine test commands or isolate external databases/services.
+
+`isolation: false` uses the original checkout and ignores copy exclusions. It
+retains the previous source restoration behavior and its limits: force-killing
+Moots or losing power while a mutation is active can leave a changed file. Use
+a disposable checkout for this compatibility mode.

data/docs/reporting.md

@@ -0,0 +1,70 @@
+# Reporting contract (schema version 1)
+
+Run `bundle exec moots --format json > moots-report.json`. Standard output is
+one JSON document; progress is flushed to standard error. The normal exit codes
+still apply: 0 for a nonempty all-killed run, 1 for survivors or no mutations,
+2 for operational errors, and 130 for interruption. Help/version requests print
+their usual text instead of JSON. Put `--format json` before other arguments if
+you also need option-parsing errors in JSON.
+
+## Document fields
+
+| Field | Type | Meaning |
+| --- | --- | --- |
+| `schema_version` | integer | Currently `1` |
+| `status` | string | `completed` or `error` |
+| `summary.mutations` | integer | Number of completed mutation tests |
+| `summary.killed` | integer | Completed mutations that failed their tests |
+| `summary.survived` | integer | Completed mutations that passed their tests |
+| `results` | array | Completed results in execution order |
+| `error` | string | Present on errors; describes why execution stopped |
+
+Each result has these fields:
+
+| Field | Type | Meaning |
+| --- | --- | --- |
+| `id` | string | 16 lowercase hexadecimal characters identifying the mutation |
+| `file` | string | Source path relative to the project working directory |
+| `line` | integer | One-based line containing the changed operator |
+| `start_offset` | integer | Zero-based byte offset of the replaced expression |
+| `original` | string | Original expression |
+| `mutated` | string | Replacement expression |
+| `status` | string | `killed` or `survived` |
+| `test_output` | string | Captured output from this mutation's test command |
+| `rerun` | array of strings | Executable and literal arguments for rerunning this mutation |
+
+IDs are the first 16 hexadecimal characters of SHA-256 over the compact JSON
+array `[relative_path, start_offset, original_hex_bytes, mutated_hex_bytes]`.
+Identical source at the same relative path has the same ID across checkouts.
+The reported line describes the operator, while the byte offset describes the
+whole replaced expression; these can start on different lines.
+
+## Reproduction
+
+From the original working directory, using the same source revision:
+
+```sh
+bundle exec moots --mutation MUTATION_ID
+bundle exec moots --config config/moots.yml --mutation MUTATION_ID
+```
+
+The `rerun` array preserves the configuration path, including spaces, without
+shell-specific quoting. A Ruby consumer can execute a result from its own report
+with `system(*result.fetch("rerun"))`. The baseline is always checked again.
+Missing IDs are errors, including when source changes invalidate an earlier ID.
+
+## Failure and encoding
+
+An error document retains results completed before the failure. Its summary is
+not a score for the whole intended run. A failed or interrupted mutation is not
+recorded as killed or survived. A failed baseline has an empty results array.
+Hard termination cannot produce a final document.
+
+With `--jobs N`, progress messages can arrive in completion order. Each mutation
+keeps its original index and ID; final JSON results, including partial error
+results, remain in source order. The rerun command selects one mutation and does
+not need to preserve a CLI worker-count override.
+
+Report strings are decoded as UTF-8 with invalid bytes replaced by `�`. IDs use
+the exact source bytes. The test runner combines stdout/stderr and trims leading
+and trailing whitespace before storing `test_output`.

data/exe/moots

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "moots/cli"
+
+exit Moots::CLI.run