evilution 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 646e7a441c39108d413a0b33cb28234b090e16c1614d343c40be84581fb45adf
-  data.tar.gz: fc65d99be854a51dc0354a77db413d90a8344611dc8d94a5e97ef61e91e764a9
+  metadata.gz: 67bff7d0366e8fe092534c14669ec3637ba1d95934a003f595519dca8f16fe68
+  data.tar.gz: b4545412acaedb471187e9522cb8858c07b9a83b748a58ffbd8aa2a1f0ec7a29
 SHA512:
-  metadata.gz: 38954ff26a4f48a050ca7a5d4270307157f7482836718152e03d17642df566110144c2773a5ce62ea8877ed2bdc97e6b2ccc33d49e9521e2074ad7cfc2b46b1e
-  data.tar.gz: c4a4bcbf1f59e2f8ff01138bf690132dcb183330009340b76b4d8db1d8807411c04dcb8f3a52820857b9563158a49147903a7274e1395b0f4f76047f239d625e
+  metadata.gz: 15c2460a72fc5822ddecc3e38c4e60424bc96a24274542ce2492c55e9a847ca02484ec103513791f91c285f3ee18b8fb3017009a146fc517822c9a1749f2cd93
+  data.tar.gz: 98f93f7b5bbe2baf2172bee631a44fa8cde99e5913e3484b91c06d780ea2f0d7f462e6a030187d3179dfbe0b0bd9d78afdeff29dd28e38e7d7b9f6efa90763c1

data/.beads/.migration-hint-ts

@@ -1 +1 @@
-1773300459
+1773589314

data/.beads/issues.jsonl

@@ -31,10 +31,10 @@
 {"id":"EV-2.9","title":"Implement Evilution::Isolation::Fork","description":"Fork-based process isolation. Method: run(mutation, test_command, timeout:) -> MutationResult. Flow: create pipe, fork child, child applies mutation via eval, child runs test command, marshal result back via pipe, parent reads with IO.select timeout, SIGKILL on deadline. File: lib/evilution/isolation/fork.rb + spec.","status":"closed","priority":2,"issue_type":"task","owner":"denis.kiselyov@gmail.com","created_at":"2026-03-02T00:05:51.142167275+07:00","created_by":"Denis Kiselev","updated_at":"2026-03-02T10:54:08.819310594+07:00","closed_at":"2026-03-02T10:54:08.819310594+07:00","close_reason":"Fork isolation implemented with 6 passing specs","dependencies":[{"issue_id":"EV-2.9","depends_on_id":"EV-2","type":"parent-child","created_at":"0001-01-01T00:00:00Z"},{"issue_id":"EV-2.9","depends_on_id":"EV-2.8","type":"blocks","created_at":"0001-01-01T00:00:00Z"}]}
 {"id":"EV-20","title":"Deprecate coverage filtering","description":"With line-range and method-name targeting, coverage collection adds overhead for little benefit. Deprecate --no-coverage flag, coverage config key, and remove coverage logic from runner.","status":"closed","priority":2,"issue_type":"task","owner":"denis.kiselyov@gmail.com","created_at":"2026-03-10T00:30:58.837659684+07:00","created_by":"Denis Kiselev","updated_at":"2026-03-10T00:33:06.453669976+07:00","closed_at":"2026-03-10T00:33:06.453669976+07:00","close_reason":"Deprecated coverage filtering: CLI warns on --no-coverage, config warns on coverage key, runner no longer uses coverage logic"}
 {"id":"EV-21","title":"Epic: Speed & Performance","description":"Reduce mutation testing wall-clock time for fast agent feedback loops. Includes fail-fast, parallel execution, and per-mutation spec targeting.","status":"open","priority":1,"issue_type":"feature","owner":"denis.kiselyov@gmail.com","created_at":"2026-03-10T06:17:26.608316104+07:00","created_by":"Denis Kiselev","updated_at":"2026-03-10T06:17:26.608316104+07:00","dependencies":[{"issue_id":"EV-21","depends_on_id":"EV-22","type":"blocks","created_at":"0001-01-01T00:00:00Z"},{"issue_id":"EV-21","depends_on_id":"EV-23","type":"blocks","created_at":"0001-01-01T00:00:00Z"}]}
-{"id":"EV-22","title":"Add --fail-fast flag with survivor threshold","description":"Add --fail-fast [N] CLI flag and fail_fast config option to stop mutation testing after N surviving mutants (default N=1 when flag given without value). Agents fix gaps iteratively, so discovering all survivors upfront is wasted work. A threshold gives control over the speed/thoroughness tradeoff: --fail-fast 1 for quick checks, --fail-fast 5 for CI gates, omit for full scans. Runner#call should stop running mutations and return a partial Summary once the threshold is reached. JSON output should include a 'truncated: true' field when fail-fast triggered.","status":"open","priority":2,"issue_type":"feature","owner":"denis.kiselyov@gmail.com","created_at":"2026-03-10T06:17:28.018733235+07:00","created_by":"Denis Kiselev","updated_at":"2026-03-10T10:29:42.228568154+07:00"}
+{"id":"EV-22","title":"Add --fail-fast flag with survivor threshold","description":"Add --fail-fast [N] CLI flag and fail_fast config option to stop mutation testing after N surviving mutants (default N=1 when flag given without value). Agents fix gaps iteratively, so discovering all survivors upfront is wasted work. A threshold gives control over the speed/thoroughness tradeoff: --fail-fast 1 for quick checks, --fail-fast 5 for CI gates, omit for full scans. Runner#call should stop running mutations and return a partial Summary once the threshold is reached. JSON output should include a 'truncated: true' field when fail-fast triggered.","status":"in_progress","priority":2,"issue_type":"feature","owner":"denis.kiselyov@gmail.com","created_at":"2026-03-10T06:17:28.018733235+07:00","created_by":"Denis Kiselev","updated_at":"2026-03-13T08:24:05.534981769+07:00"}
 {"id":"EV-23","title":"Per-mutation spec targeting","description":"Instead of running the full spec suite for every mutation, map each mutated source file to its relevant spec file(s) using convention-based resolution (e.g. lib/foo/bar.rb -> spec/foo/bar_spec.rb) and only run those. This dramatically reduces per-mutation test time. Depends on convention-based spec file resolution being implemented first.","status":"open","priority":2,"issue_type":"feature","owner":"denis.kiselyov@gmail.com","created_at":"2026-03-10T06:17:28.98620973+07:00","created_by":"Denis Kiselev","updated_at":"2026-03-10T06:17:28.98620973+07:00","dependencies":[{"issue_id":"EV-23","depends_on_id":"EV-34","type":"blocks","created_at":"0001-01-01T00:00:00Z"}]}
-{"id":"EV-24","title":"Epic: JSON Output Improvements","description":"Make JSON output fully machine-parseable in all scenarios, including errors. Add diagnostic fields that help agents debug failures.","status":"open","priority":2,"issue_type":"feature","owner":"denis.kiselyov@gmail.com","created_at":"2026-03-10T06:17:37.450686472+07:00","created_by":"Denis Kiselev","updated_at":"2026-03-10T06:17:37.450686472+07:00","dependencies":[{"issue_id":"EV-24","depends_on_id":"EV-25","type":"blocks","created_at":"0001-01-01T00:00:00Z"},{"issue_id":"EV-24","depends_on_id":"EV-26","type":"blocks","created_at":"0001-01-01T00:00:00Z"}]}
-{"id":"EV-25","title":"Structured error responses in JSON mode","description":"When --format json is used and exit code is 2 (error), output a JSON object with error details instead of unstructured stderr text. Schema: { \"error\": { \"type\": \"config_error|parse_error|runtime_error\", \"message\": \"...\", \"file\": \"...\" } }. Agents currently have to regex-parse stderr which is fragile.","status":"open","priority":2,"issue_type":"feature","owner":"denis.kiselyov@gmail.com","created_at":"2026-03-10T06:17:38.283715502+07:00","created_by":"Denis Kiselev","updated_at":"2026-03-10T06:17:38.283715502+07:00"}
+{"id":"EV-24","title":"Epic: JSON Output Improvements","description":"Make JSON output fully machine-parseable in all scenarios, including errors. Add diagnostic fields that help agents debug failures.","status":"open","priority":1,"issue_type":"feature","owner":"denis.kiselyov@gmail.com","created_at":"2026-03-10T06:17:37.450686472+07:00","created_by":"Denis Kiselev","updated_at":"2026-03-13T09:57:11.531255221+07:00","dependencies":[{"issue_id":"EV-24","depends_on_id":"EV-25","type":"blocks","created_at":"0001-01-01T00:00:00Z"},{"issue_id":"EV-24","depends_on_id":"EV-26","type":"blocks","created_at":"0001-01-01T00:00:00Z"},{"issue_id":"EV-24","depends_on_id":"EV-40","type":"blocks","created_at":"0001-01-01T00:00:00Z"}]}
+{"id":"EV-25","title":"Structured error responses in JSON mode","description":"When --format json is used and exit code is 2 (error), output a JSON object with error details instead of unstructured stderr text. Schema: { \"error\": { \"type\": \"config_error|parse_error|runtime_error\", \"message\": \"...\", \"file\": \"...\" } }. Agents currently have to regex-parse stderr which is fragile.","status":"closed","priority":1,"issue_type":"feature","owner":"denis.kiselyov@gmail.com","created_at":"2026-03-10T06:17:38.283715502+07:00","created_by":"Denis Kiselev","updated_at":"2026-03-15T22:41:54.370789377+07:00","closed_at":"2026-03-15T22:41:54.370789377+07:00","close_reason":"Merged PR #74 — structured JSON error output in CLI"}
 {"id":"EV-26","title":"Include test command in mutation result JSON","description":"Add a 'test_command' field to each mutation result in JSON output showing the exact command that was run to test that mutation. Helps agents debug when a mutation errors out or times out.","status":"open","priority":3,"issue_type":"feature","owner":"denis.kiselyov@gmail.com","created_at":"2026-03-10T06:17:39.227881462+07:00","created_by":"Denis Kiselev","updated_at":"2026-03-10T06:17:39.227881462+07:00"}
 {"id":"EV-27","title":"Epic: Workflow Integration","description":"Make evilution easier to invoke from AI agent toolchains — MCP server for direct tool calls, stdin mode for piping.","status":"open","priority":2,"issue_type":"feature","owner":"denis.kiselyov@gmail.com","created_at":"2026-03-10T06:17:43.883767452+07:00","created_by":"Denis Kiselev","updated_at":"2026-03-10T06:17:43.883767452+07:00","dependencies":[{"issue_id":"EV-27","depends_on_id":"EV-28","type":"blocks","created_at":"0001-01-01T00:00:00Z"},{"issue_id":"EV-27","depends_on_id":"EV-29","type":"blocks","created_at":"0001-01-01T00:00:00Z"}]}
 {"id":"EV-28","title":"MCP server for direct tool invocation","description":"Implement a Model Context Protocol (MCP) server that exposes evilution as a tool. Agents could call evilution directly instead of shelling out and parsing output. The server should expose a 'mutate' tool that accepts target files, options, and returns structured results.","status":"open","priority":2,"issue_type":"feature","owner":"denis.kiselyov@gmail.com","created_at":"2026-03-10T06:17:45.29866593+07:00","created_by":"Denis Kiselev","updated_at":"2026-03-10T06:17:45.29866593+07:00"}
@@ -64,8 +64,8 @@
 {"id":"EV-30","title":"Epic: Smarter Suggestions","description":"Improve the suggestion field in mutation results to provide concrete, actionable test code that agents can use directly.","status":"open","priority":2,"issue_type":"feature","owner":"denis.kiselyov@gmail.com","created_at":"2026-03-10T06:18:03.590579846+07:00","created_by":"Denis Kiselev","updated_at":"2026-03-10T06:18:03.590579846+07:00","dependencies":[{"issue_id":"EV-30","depends_on_id":"EV-31","type":"blocks","created_at":"0001-01-01T00:00:00Z"}]}
 {"id":"EV-31","title":"Generate concrete RSpec test code in suggestions","description":"Replace prose suggestions like 'add a test that checks the boundary' with actual RSpec code snippets that would kill the mutant. Use the mutation's operator, file context, and method signature to generate a concrete test example. The suggestion should be a valid RSpec 'it' block that an agent can drop into a spec file.","status":"open","priority":2,"issue_type":"feature","owner":"denis.kiselyov@gmail.com","created_at":"2026-03-10T06:18:05.964542284+07:00","created_by":"Denis Kiselev","updated_at":"2026-03-10T06:18:05.964542284+07:00"}
 {"id":"EV-32","title":"Epic: Zero-friction Defaults","description":"Make evilution work well with zero configuration. Auto-detect what to mutate and which specs to run based on git state and file conventions.","status":"open","priority":2,"issue_type":"feature","owner":"denis.kiselyov@gmail.com","created_at":"2026-03-10T06:18:06.843446356+07:00","created_by":"Denis Kiselev","updated_at":"2026-03-10T06:18:06.843446356+07:00","dependencies":[{"issue_id":"EV-32","depends_on_id":"EV-33","type":"blocks","created_at":"0001-01-01T00:00:00Z"},{"issue_id":"EV-32","depends_on_id":"EV-34","type":"blocks","created_at":"0001-01-01T00:00:00Z"}]}
-{"id":"EV-33","title":"Auto-detect changed files from git merge base","description":"When evilution is run with no file arguments, default to mutating files changed since the merge base of the current branch (git merge-base HEAD main). This makes 'evilution run --format json' just work in a feature branch without specifying files. Should be skippable if explicit files are provided.","status":"open","priority":2,"issue_type":"feature","owner":"denis.kiselyov@gmail.com","created_at":"2026-03-10T06:18:08.235421922+07:00","created_by":"Denis Kiselev","updated_at":"2026-03-10T06:18:08.235421922+07:00"}
-{"id":"EV-34","title":"Convention-based spec file resolution","description":"Implement a mapping from source files to their spec files using Ruby/RSpec conventions: lib/foo/bar.rb -> spec/foo/bar_spec.rb, app/models/user.rb -> spec/models/user_spec.rb. This is a foundational piece used by both zero-friction defaults (auto-detect specs) and per-mutation spec targeting (run only relevant specs). Should handle common Rails and gem layouts.","status":"open","priority":2,"issue_type":"feature","owner":"denis.kiselyov@gmail.com","created_at":"2026-03-10T06:18:09.380269033+07:00","created_by":"Denis Kiselev","updated_at":"2026-03-10T06:18:09.380269033+07:00"}
+{"id":"EV-33","title":"Auto-detect changed files from git merge base","description":"When evilution is run with no file arguments, default to mutating files changed since the merge base of the current branch (git merge-base HEAD main). This makes 'evilution run --format json' just work in a feature branch without specifying files. Should be skippable if explicit files are provided.","status":"in_progress","priority":2,"issue_type":"feature","owner":"denis.kiselyov@gmail.com","created_at":"2026-03-10T06:18:08.235421922+07:00","created_by":"Denis Kiselev","updated_at":"2026-03-15T23:20:23.413703926+07:00"}
+{"id":"EV-34","title":"Convention-based spec file resolution","description":"Implement a mapping from source files to their spec files using Ruby/RSpec conventions: lib/foo/bar.rb -> spec/foo/bar_spec.rb, app/models/user.rb -> spec/models/user_spec.rb. This is a foundational piece used by both zero-friction defaults (auto-detect specs) and per-mutation spec targeting (run only relevant specs). Should handle common Rails and gem layouts.","status":"in_progress","priority":2,"issue_type":"feature","owner":"denis.kiselyov@gmail.com","created_at":"2026-03-10T06:18:09.380269033+07:00","created_by":"Denis Kiselev","updated_at":"2026-03-15T22:50:31.462784114+07:00"}
 {"id":"EV-35","title":"File left in mutated state on timeout","description":"Epic: File left in mutated state on timeout. Root cause: SIGKILL (fork.rb:45) is untrappable — child's ensure block (rspec.rb:24-26) never runs, so restore_original never executes. Affects Strategy B (direct file write) with data corruption and Strategy A (temp dir) with resource leaks. Decomposed into EV-37, EV-38, EV-39.","status":"closed","priority":1,"issue_type":"bug","owner":"denis.kiselyov@gmail.com","created_at":"2026-03-12T14:27:59.54425065+07:00","created_by":"Denis Kiselev","updated_at":"2026-03-13T00:34:44.130203912+07:00","closed_at":"2026-03-13T00:34:44.130203912+07:00","close_reason":"All sub-issues (EV-37, EV-38, EV-39) completed","dependencies":[{"issue_id":"EV-35","depends_on_id":"EV-37","type":"blocks","created_at":"0001-01-01T00:00:00Z"},{"issue_id":"EV-35","depends_on_id":"EV-38","type":"blocks","created_at":"0001-01-01T00:00:00Z"},{"issue_id":"EV-35","depends_on_id":"EV-39","type":"blocks","created_at":"0001-01-01T00:00:00Z"}]}
 {"id":"EV-36","title":"Raise default timeout from 10s to 30s","description":"Default 10s timeout is too low when running the full test suite per mutation (no smart test selection yet). Agent testing showed 30s was needed. Raising the default prevents confusing timeout failures for new users.","status":"closed","priority":2,"issue_type":"task","owner":"denis.kiselyov@gmail.com","created_at":"2026-03-12T14:27:59.761882257+07:00","created_by":"Denis Kiselev","updated_at":"2026-03-12T14:45:27.102490973+07:00","closed_at":"2026-03-12T14:45:27.102490973+07:00","close_reason":"Closed"}
 {"id":"EV-37","title":"Parent-side backup & restore for direct-write mutations","description":"Root cause: SIGKILL is untrappable, so when a mutation times out the child's ensure block (rspec.rb:24-26) never runs. If Strategy B (direct file write, rspec.rb:50-58) was used, the original file is left in a mutated state on disk. Fix: before forking, the parent must save a backup of the original file content. After the child exits (normally or via kill), the parent verifies the file is restored and restores it if not. This is the primary fix for EV-35.","status":"closed","priority":0,"issue_type":"bug","owner":"denis.kiselyov@gmail.com","created_at":"2026-03-12T14:32:49.590919391+07:00","created_by":"Denis Kiselev","updated_at":"2026-03-12T23:04:21.990924732+07:00","closed_at":"2026-03-12T23:04:21.990924732+07:00","close_reason":"Implemented parent-side restore in Fork#call ensure block with read-before-write guard"}
@@ -81,6 +81,10 @@
 {"id":"EV-4.7","title":"Integrate parallel execution into Runner","description":"Update Runner to use Parallel::Pool when jobs > 1. Replace sequential mutation execution with pool.run. Verify results are identical. File: lib/evilution/runner.rb (edit).","status":"closed","priority":2,"issue_type":"task","owner":"denis.kiselyov@gmail.com","created_at":"2026-03-02T00:06:45.637953763+07:00","created_by":"Denis Kiselev","updated_at":"2026-03-02T11:54:25.596270941+07:00","closed_at":"2026-03-02T11:54:25.596270941+07:00","close_reason":"Closed","dependencies":[{"issue_id":"EV-4.7","depends_on_id":"EV-4","type":"parent-child","created_at":"0001-01-01T00:00:00Z"},{"issue_id":"EV-4.7","depends_on_id":"EV-4.1","type":"blocks","created_at":"0001-01-01T00:00:00Z"},{"issue_id":"EV-4.7","depends_on_id":"EV-2.12","type":"blocks","created_at":"0001-01-01T00:00:00Z"}]}
 {"id":"EV-4.8","title":"Integrate coverage-based filtering into Runner","description":"Update Runner to optionally collect coverage on first test suite run, build TestMap, and skip mutations on uncovered lines. Controlled by --no-coverage flag. File: lib/evilution/runner.rb (edit).","status":"closed","priority":2,"issue_type":"task","owner":"denis.kiselyov@gmail.com","created_at":"2026-03-02T00:06:45.745583233+07:00","created_by":"Denis Kiselev","updated_at":"2026-03-06T11:02:35.638752306+07:00","closed_at":"2026-03-02T11:54:25.596274893+07:00","close_reason":"Closed","dependencies":[{"issue_id":"EV-4.8","depends_on_id":"EV-4","type":"parent-child","created_at":"0001-01-01T00:00:00Z"},{"issue_id":"EV-4.8","depends_on_id":"EV-4.4","type":"blocks","created_at":"0001-01-01T00:00:00Z"},{"issue_id":"EV-4.8","depends_on_id":"EV-2.12","type":"blocks","created_at":"0001-01-01T00:00:00Z"}]}
 {"id":"EV-4.9","title":"Integrate diff-based targeting into Runner","description":"Update Runner to optionally use Diff::Parser + FileFilter when --diff flag is set. Filter subjects before mutation generation. File: lib/evilution/runner.rb (edit).","status":"closed","priority":2,"issue_type":"task","owner":"denis.kiselyov@gmail.com","created_at":"2026-03-02T00:06:45.851982561+07:00","created_by":"Denis Kiselev","updated_at":"2026-03-02T11:54:25.596280246+07:00","closed_at":"2026-03-02T11:54:25.596280246+07:00","close_reason":"Closed","dependencies":[{"issue_id":"EV-4.9","depends_on_id":"EV-4","type":"parent-child","created_at":"0001-01-01T00:00:00Z"},{"issue_id":"EV-4.9","depends_on_id":"EV-4.6","type":"blocks","created_at":"0001-01-01T00:00:00Z"},{"issue_id":"EV-4.9","depends_on_id":"EV-2.12","type":"blocks","created_at":"0001-01-01T00:00:00Z"}]}
+{"id":"EV-40","title":"Separate rspec noise from evilution output (stdout/stderr)","description":"RSpec warnings flood stdout and corrupt JSON output. When using --format json, the JSON gets buried in hundreds of lines of rspec warnings. Fix: redirect rspec subprocess output to stderr (or /dev/null), keep evilution results on stdout. Critical for piping JSON output.","status":"open","priority":1,"issue_type":"bug","owner":"denis.kiselyov@gmail.com","created_at":"2026-03-13T09:56:58.604909176+07:00","created_by":"Denis Kiselev","updated_at":"2026-03-13T09:56:58.604909176+07:00"}
+{"id":"EV-41","title":"Progress indicator during mutation runs","description":"Zero output during multi-minute runs makes it look stuck. Add a simple 'mutation 3/19 killed...' progress line to stderr so users know work is happening. Only show in text mode or when stderr is a TTY.","status":"open","priority":2,"issue_type":"feature","owner":"denis.kiselyov@gmail.com","created_at":"2026-03-13T09:57:01.023293323+07:00","created_by":"Denis Kiselev","updated_at":"2026-03-13T09:57:01.023293323+07:00"}
+{"id":"EV-42","title":"Expand mutation operators (method call removal, receiver replacement, etc.)","description":"Currently 18 operators generating ~19 mutations vs mutant's 78 for the same method. Missing operators: method call removal, self receiver replacement, additional boolean logic mutations, nil substitutions. Higher operator count catches more subtle bugs and produces a more meaningful mutation score.","status":"open","priority":2,"issue_type":"feature","owner":"denis.kiselyov@gmail.com","created_at":"2026-03-13T09:57:03.039944039+07:00","created_by":"Denis Kiselev","updated_at":"2026-03-13T09:57:03.039944039+07:00"}
+{"id":"EV-43","title":"Fix --version flag (returns 'version unknown')","description":"Running 'evilution --version' returns 'version unknown' instead of the actual version. The 'evilution version' subcommand works, but --version as a flag does not. Users expect --version to work.","status":"open","priority":1,"issue_type":"bug","owner":"denis.kiselyov@gmail.com","created_at":"2026-03-13T09:57:05.048211823+07:00","created_by":"Denis Kiselev","updated_at":"2026-03-13T09:57:05.048211823+07:00"}
 {"id":"EV-5","title":"Phase 4: Polish","description":"Suggestion generator, .evilution.yml config file loading, evilution init subcommand, error handling, README","status":"closed","priority":2,"issue_type":"epic","owner":"denis.kiselyov@gmail.com","created_at":"2026-03-02T00:05:03.497091872+07:00","created_by":"Denis Kiselev","updated_at":"2026-03-02T11:54:32.782883746+07:00","closed_at":"2026-03-02T11:54:32.782883746+07:00","close_reason":"Closed","dependencies":[{"issue_id":"EV-5","depends_on_id":"EV-4","type":"blocks","created_at":"0001-01-01T00:00:00Z"}]}
 {"id":"EV-5.1","title":"Implement Evilution::Reporter::Suggestion","description":"Generates actionable fix suggestions per surviving mutant. Each operator type has a suggestion template. E.g., ComparisonReplacement >= -> > suggests 'Add a test for the boundary case where value equals exactly [threshold]'. File: lib/evilution/reporter/suggestion.rb + spec.","status":"closed","priority":2,"issue_type":"task","owner":"denis.kiselyov@gmail.com","created_at":"2026-03-02T00:06:58.038411009+07:00","created_by":"Denis Kiselev","updated_at":"2026-03-02T11:54:21.518470747+07:00","closed_at":"2026-03-02T11:54:21.518470747+07:00","close_reason":"Closed","dependencies":[{"issue_id":"EV-5.1","depends_on_id":"EV-5","type":"parent-child","created_at":"0001-01-01T00:00:00Z"},{"issue_id":"EV-5.1","depends_on_id":"EV-2.8","type":"blocks","created_at":"0001-01-01T00:00:00Z"},{"issue_id":"EV-5.1","depends_on_id":"EV-3.21","type":"blocks","created_at":"0001-01-01T00:00:00Z"}]}
 {"id":"EV-5.2","title":"Implement .evilution.yml config file loading","description":"Load config from .evilution.yml / config/evilution.yml if present. YAML keys map to Config fields. CLI flags override file values. File: update lib/evilution/config.rb + spec.","status":"closed","priority":2,"issue_type":"task","owner":"denis.kiselyov@gmail.com","created_at":"2026-03-02T00:06:58.142538793+07:00","created_by":"Denis Kiselev","updated_at":"2026-03-02T11:54:21.518473527+07:00","closed_at":"2026-03-02T11:54:21.518473527+07:00","close_reason":"Closed","dependencies":[{"issue_id":"EV-5.2","depends_on_id":"EV-5","type":"parent-child","created_at":"0001-01-01T00:00:00Z"},{"issue_id":"EV-5.2","depends_on_id":"EV-2.1","type":"blocks","created_at":"0001-01-01T00:00:00Z"}]}

data/lib/evilution/ast/parser.rb

@@ -6,12 +6,16 @@ module Evilution
   module AST
     class Parser
       def call(file_path)
-        raise ParseError, "file not found: #{file_path}" unless File.exist?(file_path)
+        raise ParseError.new("file not found: #{file_path}", file: file_path) unless File.exist?(file_path)
 
-        source = File.read(file_path)
+        begin
+          source = File.read(file_path)
+        rescue SystemCallError => e
+          raise ParseError.new("cannot read #{file_path}: #{e.message}", file: file_path)
+        end
         result = Prism.parse(source)
 
-        raise ParseError, "failed to parse #{file_path}: #{result.errors.map(&:message).join(", ")}" if result.failure?
+        raise ParseError.new("failed to parse #{file_path}: #{result.errors.map(&:message).join(", ")}", file: file_path) if result.failure?
 
         extract_subjects(result.value, source, file_path)
       end

data/lib/evilution/cli.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require "json"
 require "optparse"
 require_relative "version"
 require_relative "config"
@@ -12,7 +13,7 @@ module Evilution
       @command = :run
       argv = argv.dup
       argv = extract_command(argv)
-      argv = warn_removed_flags(argv)
+      argv = preprocess_flags(argv)
       raw_args = build_option_parser.parse!(argv)
       @files, @line_ranges = parse_file_args(raw_args)
     end
@@ -45,7 +46,7 @@ module Evilution
       argv
     end
 
-    def warn_removed_flags(argv)
+    def preprocess_flags(argv)
       result = []
       i = 0
       while i < argv.length
@@ -53,10 +54,24 @@ module Evilution
         if %w[--jobs -j].include?(arg)
           warn("Warning: --jobs is no longer supported and will be ignored.")
           next_arg = argv[i + 1]
-          i += next_arg&.match?(/\A-?\d+\z/) ? 2 : 1
+          numeric_next = next_arg && next_arg.match?(/\A-?\d+\z/)
+          i += numeric_next ? 2 : 1
         elsif arg.start_with?("--jobs=") || arg.match?(/\A-j-?\d+\z/)
           warn("Warning: --jobs is no longer supported and will be ignored.")
           i += 1
+        elsif arg == "--fail-fast"
+          next_arg = argv[i + 1]
+
+          if next_arg && next_arg.match?(/\A-?\d+\z/)
+            @options[:fail_fast] = next_arg
+            i += 2
+          else
+            result << arg
+            i += 1
+          end
+        elsif arg.start_with?("--fail-fast=")
+          @options[:fail_fast] = arg.delete_prefix("--fail-fast=")
+          i += 1
         else
           result << arg
           i += 1
@@ -97,6 +112,8 @@ module Evilution
         warn("Warning: --no-coverage is deprecated, currently has no effect, and will be removed in a future version.")
         @options[:coverage] = false
       end
+      opts.on("--fail-fast", "Stop after N surviving mutants " \
+                             "(default: disabled; if provided without N, uses 1; use --fail-fast=N)") { @options[:fail_fast] ||= 1 }
       opts.on("-v", "--verbose", "Verbose output") { @options[:verbose] = true }
       opts.on("-q", "--quiet", "Suppress output") { @options[:quiet] = true }
     end
@@ -141,13 +158,37 @@ module Evilution
     end
 
     def run_mutations
+      file_options = Config.file_options
       config = Config.new(**@options, target_files: @files, line_ranges: @line_ranges)
       runner = Runner.new(config: config)
       summary = runner.call
       summary.success?(min_score: config.min_score) ? 0 : 1
     rescue Error => e
-      warn("Error: #{e.message}")
+      if json_format?(config, file_options)
+        $stdout.puts(JSON.generate(error_payload(e)))
+      else
+        warn("Error: #{e.message}")
+      end
       2
     end
+
+    def json_format?(config, file_options)
+      return config.json? if config
+
+      format = @options[:format] || (file_options && file_options[:format])
+      format && format.to_sym == :json
+    end
+
+    def error_payload(error)
+      error_type = case error
+                   when ConfigError then "config_error"
+                   when ParseError then "parse_error"
+                   else "runtime_error"
+                   end
+
+      payload = { type: error_type, message: error.message }
+      payload[:file] = error.file if error.file
+      { error: payload }
+    end
   end
 end

data/lib/evilution/config.rb

@@ -16,13 +16,14 @@ module Evilution
       coverage: true,
       verbose: false,
       quiet: false,
+      fail_fast: nil,
       line_ranges: {},
       spec_files: []
     }.freeze
 
     attr_reader :target_files, :timeout, :format, :diff_base,
                 :target, :min_score, :integration, :coverage, :verbose, :quiet,
-                :line_ranges, :spec_files
+                :fail_fast, :line_ranges, :spec_files
 
     def initialize(**options)
       file_options = options.delete(:skip_config_file) ? {} : load_config_file
@@ -38,6 +39,7 @@ module Evilution
       @coverage = merged[:coverage]
       @verbose = merged[:verbose]
       @quiet = merged[:quiet]
+      @fail_fast = validate_fail_fast(merged[:fail_fast])
       @line_ranges = merged[:line_ranges] || {}
       @spec_files = Array(merged[:spec_files])
       freeze
@@ -63,6 +65,25 @@ module Evilution
       !target.nil?
     end
 
+    def fail_fast?
+      !fail_fast.nil?
+    end
+
+    def self.file_options
+      CONFIG_FILES.each do |path|
+        next unless File.exist?(path)
+
+        data = YAML.safe_load_file(path, symbolize_names: true)
+        return data.is_a?(Hash) ? data : {}
+      rescue Psych::SyntaxError, Psych::DisallowedClass => e
+        raise ConfigError.new("failed to parse config file #{path}: #{e.message}", file: path)
+      rescue SystemCallError => e
+        raise ConfigError.new("cannot read config file #{path}: #{e.message}", file: path)
+      end
+
+      {}
+    end
+
     # Generates a default config file template.
     def self.default_template
       <<~YAML
@@ -81,6 +102,9 @@ module Evilution
         # Test integration: rspec (default: rspec)
         # integration: rspec
 
+        # Stop after N surviving mutants (default: disabled)
+        # fail_fast: 1
+
         # DEPRECATED: Coverage filtering is deprecated and will be removed
         # coverage: true
       YAML
@@ -88,6 +112,17 @@ module Evilution
 
     private
 
+    def validate_fail_fast(value)
+      return nil if value.nil?
+
+      value = Integer(value)
+      raise ConfigError, "fail_fast must be a positive integer, got #{value}" unless value >= 1
+
+      value
+    rescue ::ArgumentError, ::TypeError
+      raise ConfigError, "fail_fast must be a positive integer, got #{value.inspect}"
+    end
+
     def warn_removed_options(merged, file_options)
       if merged.key?(:jobs)
         warn("Warning: 'jobs' option is no longer supported and will be ignored. " \
@@ -106,14 +141,7 @@ module Evilution
     end
 
     def load_config_file
-      CONFIG_FILES.each do |path|
-        next unless File.exist?(path)
-
-        data = YAML.safe_load_file(path, symbolize_names: true)
-        return data.is_a?(Hash) ? data : {}
-      end
-
-      {}
+      self.class.file_options
     end
   end
 end

data/lib/evilution/git/changed_files.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require "English"
+
+module Evilution
+  module Git
+    class ChangedFiles
+      MAIN_BRANCHES = %w[main master origin/main origin/master].freeze
+      SOURCE_PREFIXES = %w[lib/ app/].freeze
+
+      def call
+        main_branch = detect_main_branch
+        merge_base = run_git("merge-base", "HEAD", main_branch)
+        diff_output = run_git("diff", "--name-only", "--diff-filter=ACMR", "#{merge_base}..HEAD")
+
+        files = diff_output.split("\n").select { |f| ruby_source_file?(f) }
+        raise Error, "no changed Ruby files found since merge base with #{main_branch}" if files.empty?
+
+        files
+      end
+
+      private
+
+      def detect_main_branch
+        MAIN_BRANCHES.each do |branch|
+          return branch if branch_exists?(branch)
+        end
+
+        raise Error, "could not detect main branch (tried #{MAIN_BRANCHES.join(", ")})"
+      end
+
+      def branch_exists?(name)
+        run_git("rev-parse", "--verify", name)
+        true
+      rescue Error => e
+        raise if e.message.include?("not a git repository")
+
+        false
+      end
+
+      def ruby_source_file?(path)
+        path.end_with?(".rb") && SOURCE_PREFIXES.any? { |prefix| path.start_with?(prefix) }
+      end
+
+      def run_git(*args)
+        output = `git #{args.join(" ")} 2>&1`.strip
+        raise Error, "not a git repository" if output.include?("not a git repository")
+        raise Error, "git command failed: git #{args.join(" ")}: #{output}" unless $CHILD_STATUS.success?
+
+        output
+      end
+    end
+  end
+end

data/lib/evilution/integration/rspec.rb

@@ -100,12 +100,13 @@ module Evilution
         out = StringIO.new
         err = StringIO.new
         args = build_args(mutation)
+        command = "rspec #{args.join(" ")}"
 
         status = ::RSpec::Core::Runner.run(args, out, err)
 
-        { passed: status.zero? }
+        { passed: status.zero?, test_command: command }
       rescue StandardError => e
-        { passed: false, error: e.message }
+        { passed: false, error: e.message, test_command: command }
       end
 
       def build_args(_mutation)

data/lib/evilution/isolation/fork.rb

@@ -91,7 +91,8 @@ module Evilution
         Result::MutationResult.new(
           mutation: mutation,
           status: status,
-          duration: duration
+          duration: duration,
+          test_command: result[:test_command]
         )
       end
     end

data/lib/evilution/reporter/cli.rb

@@ -23,6 +23,7 @@ module Evilution
         end
 
         lines << ""
+        lines << "[TRUNCATED] Stopped early due to --fail-fast" if summary.truncated?
         lines << result_line(summary)
 
         lines.join("\n")

data/lib/evilution/reporter/json.rb

@@ -30,7 +30,7 @@ module Evilution
       end
 
       def build_summary(summary)
-        {
+        data = {
           total: summary.total,
           killed: summary.killed,
           survived: summary.survived,
@@ -39,6 +39,8 @@ module Evilution
           score: summary.score.round(4),
           duration: summary.duration.round(4)
         }
+        data[:truncated] = true if summary.truncated?
+        data
       end
 
       def build_mutation_detail(result)
@@ -52,6 +54,7 @@ module Evilution
           diff: mutation.diff
         }
         detail[:suggestion] = @suggestion.suggestion_for(mutation) if result.status == :survived
+        detail[:test_command] = result.test_command if result.test_command
         detail
       end
     end

data/lib/evilution/result/mutation_result.rb

@@ -5,15 +5,16 @@ module Evilution
     class MutationResult
       STATUSES = %i[killed survived timeout error].freeze
 
-      attr_reader :mutation, :status, :duration, :killing_test
+      attr_reader :mutation, :status, :duration, :killing_test, :test_command
 
-      def initialize(mutation:, status:, duration: 0.0, killing_test: nil)
+      def initialize(mutation:, status:, duration: 0.0, killing_test: nil, test_command: nil)
         raise ArgumentError, "invalid status: #{status}" unless STATUSES.include?(status)
 
         @mutation = mutation
         @status = status
         @duration = duration
         @killing_test = killing_test
+        @test_command = test_command
         freeze
       end
 

data/lib/evilution/result/summary.rb

@@ -5,12 +5,17 @@ module Evilution
     class Summary
       attr_reader :results, :duration
 
-      def initialize(results:, duration: 0.0)
+      def initialize(results:, duration: 0.0, truncated: false)
         @results = results
         @duration = duration
+        @truncated = truncated
         freeze
       end
 
+      def truncated?
+        @truncated
+      end
+
       def total
         results.length
       end

data/lib/evilution/runner.rb

@@ -10,6 +10,7 @@ require_relative "reporter/cli"
 require_relative "reporter/suggestion"
 require_relative "diff/parser"
 require_relative "diff/file_filter"
+require_relative "git/changed_files"
 require_relative "result/mutation_result"
 require_relative "result/summary"
 
@@ -32,10 +33,10 @@ module Evilution
       subjects = filter_by_line_ranges(subjects) if config.line_ranges?
       subjects = filter_by_diff(subjects) if config.diff?
       mutations = generate_mutations(subjects)
-      results = run_mutations(mutations)
+      results, truncated = run_mutations(mutations)
       duration = Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time
 
-      summary = Result::Summary.new(results: results, duration: duration)
+      summary = Result::Summary.new(results: results, duration: duration, truncated: truncated)
       output_report(summary)
 
       summary
@@ -46,7 +47,14 @@ module Evilution
     attr_reader :parser, :registry, :isolator
 
     def parse_subjects
-      config.target_files.flat_map { |file| parser.call(file) }
+      files = resolve_target_files
+      files.flat_map { |file| parser.call(file) }
+    end
+
+    def resolve_target_files
+      return config.target_files unless config.target_files.empty?
+
+      Git::ChangedFiles.new.call
     end
 
     def filter_by_target(subjects)
@@ -79,15 +87,27 @@ module Evilution
 
     def run_mutations(mutations)
       integration = build_integration
+      results = []
+      survived_count = 0
+      truncated = false
 
-      mutations.map do |mutation|
+      mutations.each_with_index do |mutation, index|
         test_command = ->(m) { integration.call(m) }
-        isolator.call(
+        result = isolator.call(
           mutation: mutation,
           test_command: test_command,
           timeout: config.timeout
         )
+        results << result
+        survived_count += 1 if result.survived?
+
+        if config.fail_fast? && survived_count >= config.fail_fast && index < mutations.length - 1
+          truncated = true
+          break
+        end
       end
+
+      [results, truncated]
     end
 
     def build_integration

data/lib/evilution/spec_resolver.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Evilution
+  class SpecResolver
+    STRIPPABLE_PREFIXES = %w[lib/ app/].freeze
+
+    def call(source_path)
+      return nil if source_path.nil? || source_path.empty?
+
+      normalized = normalize_path(source_path)
+      candidates = candidate_spec_paths(normalized)
+      candidates.find { |path| File.exist?(path) }
+    end
+
+    def resolve_all(source_paths)
+      Array(source_paths).filter_map { |path| call(path) }.uniq
+    end
+
+    private
+
+    def normalize_path(path)
+      path = path.delete_prefix("./")
+      path = path.delete_prefix("#{Dir.pwd}/") if path.start_with?("/")
+      path
+    end
+
+    def candidate_spec_paths(source_path)
+      base = source_path.sub(/\.rb\z/, "_spec.rb")
+      prefix = STRIPPABLE_PREFIXES.find { |p| source_path.start_with?(p) }
+
+      if prefix
+        stripped = "spec/#{base.delete_prefix(prefix)}"
+        kept = "spec/#{base}"
+        [stripped, kept]
+      else
+        ["spec/#{base}"]
+      end
+    end
+  end
+end

data/lib/evilution/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Evilution
-  VERSION = "0.3.0"
+  VERSION = "0.4.0"
 end

data/lib/evilution.rb

@@ -29,6 +29,7 @@ require_relative "evilution/mutator/registry"
 require_relative "evilution/isolation/fork"
 require_relative "evilution/diff/parser"
 require_relative "evilution/diff/file_filter"
+require_relative "evilution/git/changed_files"
 require_relative "evilution/integration/base"
 require_relative "evilution/integration/rspec"
 require_relative "evilution/result/mutation_result"
@@ -38,11 +39,20 @@ require_relative "evilution/reporter/cli"
 require_relative "evilution/reporter/suggestion"
 require_relative "evilution/coverage/collector"
 require_relative "evilution/coverage/test_map"
+require_relative "evilution/spec_resolver"
 require_relative "evilution/cli"
 require_relative "evilution/runner"
 
 module Evilution
-  class Error < StandardError; end
+  class Error < StandardError
+    attr_reader :file
+
+    def initialize(message = nil, file: nil)
+      super(message)
+      @file = file
+    end
+  end
+
   class ConfigError < Error; end
   class ParseError < Error; end
   class IsolationError < Error; end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: evilution
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Denis Kiselev
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-03-12 00:00:00.000000000 Z
+date: 2026-03-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: diff-lcs
@@ -66,6 +66,7 @@ files:
 - lib/evilution/coverage/test_map.rb
 - lib/evilution/diff/file_filter.rb
 - lib/evilution/diff/parser.rb
+- lib/evilution/git/changed_files.rb
 - lib/evilution/integration/base.rb
 - lib/evilution/integration/rspec.rb
 - lib/evilution/isolation/fork.rb
@@ -96,6 +97,7 @@ files:
 - lib/evilution/result/mutation_result.rb
 - lib/evilution/result/summary.rb
 - lib/evilution/runner.rb
+- lib/evilution/spec_resolver.rb
 - lib/evilution/subject.rb
 - lib/evilution/version.rb
 - sig/evilution.rbs