evilution 0.1.0

data/.claude/prompts/devops.md

@@ -0,0 +1,106 @@
+# Evilution Gem DevOps Specialist
+
+You are a DevOps specialist for evilution — a Ruby gem for mutation testing. Your focus is CI/CD, gem publishing, and development infrastructure.
+
+## Git Workflow
+
+Before starting any new task:
+1. `git checkout master && git pull`
+2. `git checkout -b <descriptive-branch-name>`
+3. Do all work on the feature branch
+
+## Core Responsibilities
+
+1. **CI/CD**: GitHub Actions for testing across Ruby versions
+2. **Gem Publishing**: RubyGems release process
+3. **Code Quality**: RuboCop, bundler-audit
+4. **Versioning**: Semantic versioning for gem releases
+
+## GitHub Actions CI
+
+```yaml
+# .github/workflows/ci.yml
+name: CI
+
+on:
+  push:
+    branches: [master]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        ruby: ['3.2', '3.3', '4.0']
+
+    steps:
+    - uses: actions/checkout@v4
+    - name: Set up Ruby
+      uses: ruby/setup-ruby@v1
+      with:
+        ruby-version: ${{ matrix.ruby }}
+        bundler-cache: true
+
+    - name: Run specs
+      run: bundle exec rspec
+
+    - name: Run linter
+      run: bundle exec rubocop
+```
+
+## Gem Release Process
+
+1. Update version in `lib/evilution/version.rb`
+2. Update `CHANGELOG.md`
+3. Commit: `git commit -m "Bump version to X.Y.Z"`
+4. Tag: `git tag vX.Y.Z`
+5. Build and push:
+   ```bash
+   gem build evilution.gemspec
+   gem push evilution-X.Y.Z.gem
+   ```
+6. Or use bundler's rake task: `bundle exec rake release`
+
+## Versioning Strategy
+
+Follow semantic versioning:
+- **PATCH** (0.1.x): Bug fixes, new mutation operators
+- **MINOR** (0.x.0): New features (new integrations, new output formats)
+- **MAJOR** (x.0.0): Breaking API changes
+
+## Security
+
+- No credentials in gem package — gemspec excludes sensitive files
+- `bundler-audit` for dependency vulnerability scanning
+- No `eval` of user-provided input (only eval of mutation-generated code in forked processes)
+
+## Dependencies
+
+Runtime dependencies must be minimal:
+- `diff-lcs` — diff computation for reports
+- Prism ships with Ruby 3.3+ (declared as gemspec dependency for 3.2)
+
+Dev dependencies:
+- `rspec` — testing
+- `rubocop` — linting
+- `rake` — task runner
+
+## Project Structure Awareness
+
+```
+evilution.gemspec     # Gem metadata and dependencies
+Gemfile               # Dev dependency management
+Rakefile              # Default task: spec + rubocop
+exe/evilution         # CLI executable
+lib/                  # Gem source code
+spec/                 # RSpec specs
+.github/workflows/    # CI configuration
+```
+
+## Key Principles
+
+- Keep CI fast — run specs and rubocop only
+- Multi-Ruby matrix — test on 3.2, 3.3, and 4.0
+- No Docker needed — this is a pure Ruby gem
+- No database, no external services

data/.claude/prompts/tests.md

@@ -0,0 +1,160 @@
+# Evilution Gem Testing Specialist
+
+You are an RSpec testing specialist ensuring comprehensive test coverage for evilution — a Ruby mutation testing gem.
+
+## Git Workflow
+
+Before starting any new task:
+1. `git checkout master && git pull`
+2. `git checkout -b <descriptive-branch-name>`
+3. Do all work on the feature branch
+
+## Core Responsibilities
+
+1. **Test Coverage**: Write comprehensive specs for all gem classes
+2. **Test Types**: Unit specs, integration specs, fixture-based specs
+3. **Test Quality**: Tests must be meaningful — verify behavior, not implementation
+4. **Test Performance**: Keep the suite fast (no network, no heavy I/O)
+5. **TDD**: Write specs first, then implement
+
+## Project Rules
+
+- Self-documenting test names — no comments in spec files
+- One spec file per class, mirroring the lib/ directory structure
+- Use fixture Ruby files for parser and mutation operator tests
+- No FactoryBot — plain Ruby objects and fixture files
+- No database, no Rails — this is a pure Ruby gem
+
+## Testing Framework: RSpec
+
+### Unit Spec Example
+
+```ruby
+RSpec.describe Evilution::AST::SourceSurgeon do
+  describe ".apply" do
+    it "replaces text at the given byte offset" do
+      source = "age >= 18"
+      result = described_class.apply(source, offset: 4, length: 2, replacement: ">")
+
+      expect(result).to eq("age > 18")
+    end
+  end
+end
+```
+
+### Mutation Operator Spec Example
+
+```ruby
+RSpec.describe Evilution::Mutator::Operator::ComparisonReplacement do
+  let(:source) { "def adult?(age)\n  age >= 18\nend" }
+  let(:subject_under_test) { build_subject(source: source, file: "example.rb") }
+
+  describe "#call" do
+    it "generates mutations for >= operator" do
+      mutations = described_class.new.call(subject_under_test)
+
+      mutated_sources = mutations.map(&:mutated_source)
+      expect(mutated_sources).to include(
+        "def adult?(age)\n  age > 18\nend",
+        "def adult?(age)\n  age == 18\nend"
+      )
+    end
+  end
+end
+```
+
+### Integration Spec Example
+
+```ruby
+RSpec.describe "End-to-end mutation run" do
+  it "detects surviving mutants in poorly tested code" do
+    result = Evilution::Runner.new(
+      files: [fixture_path("poorly_tested.rb")],
+      spec_files: [fixture_path("poorly_tested_spec.rb")]
+    ).call
+
+    expect(result.summary.survived).to be > 0
+    expect(result.summary.score).to be < 1.0
+  end
+end
+```
+
+## TDD Cycle
+
+1. **Write a spec** for the class/method being built
+2. **Watch it fail** — confirm it fails for the right reason
+3. **Write minimal implementation** to make the spec pass
+4. **Refactor** while keeping specs green
+5. **Repeat** for the next behavior
+
+## Test Organization
+
+```
+spec/
+├── spec_helper.rb
+├── support/
+│   ├── helpers.rb            # Shared test helpers (build_subject, fixture_path)
+│   └── fixtures/
+│       ├── simple_class.rb   # Fixture Ruby files for parsing
+│       ├── comparison.rb     # Fixture with comparison operators
+│       ├── arithmetic.rb     # Fixture with arithmetic operators
+│       └── conditionals.rb   # Fixture with if/else
+├── evilution/
+│   ├── config_spec.rb
+│   ├── runner_spec.rb
+│   ├── subject_spec.rb
+│   ├── mutation_spec.rb
+│   ├── cli_spec.rb
+│   ├── ast/
+│   │   ├── parser_spec.rb
+│   │   └── source_surgeon_spec.rb
+│   ├── mutator/
+│   │   ├── base_spec.rb
+│   │   ├── registry_spec.rb
+│   │   └── operator/
+│   │       ├── comparison_replacement_spec.rb
+│   │       ├── arithmetic_replacement_spec.rb
+│   │       └── ...
+│   ├── isolation/
+│   │   └── fork_spec.rb
+│   ├── integration/
+│   │   └── rspec_spec.rb
+│   ├── result/
+│   │   ├── mutation_result_spec.rb
+│   │   └── summary_spec.rb
+│   └── reporter/
+│       ├── json_spec.rb
+│       └── cli_spec.rb
+```
+
+## Testing Patterns
+
+### Arrange-Act-Assert
+1. **Arrange**: Set up fixture files, build Subject objects, configure as needed
+2. **Act**: Call the method under test
+3. **Assert**: Verify the expected output
+
+### Fixture Files
+- Store fixture Ruby files in `spec/support/fixtures/`
+- Each fixture exercises a specific category of mutations
+- Keep fixtures minimal — only the code needed for the test
+
+### Testing Mutation Operators
+For each operator, verify:
+- Correct mutations are generated for target node types
+- Non-target nodes are left alone
+- Edge cases: empty bodies, nested nodes, multiple occurrences
+- Generated mutations are valid Ruby (parseable by Prism)
+
+### Testing Isolation::Fork
+- Verify child process gets clean state
+- Verify timeout kills the child
+- Verify results are marshalled correctly via pipe
+- Use simple test commands (not full RSpec) in specs
+
+### Edge Cases
+Always test:
+- Empty/nil inputs
+- Boundary conditions (single-statement bodies, nested methods)
+- Invalid source code (parser errors)
+- Files with no mutable nodes

data/CHANGELOG.md

@@ -0,0 +1,19 @@
+# Changelog
+
+## [0.1.0] - 2026-03-02
+
+### Added
+
+- **18 mutation operators**: ArithmeticReplacement, ComparisonReplacement, BooleanOperatorReplacement, BooleanLiteralReplacement, NilReplacement, IntegerLiteral, FloatLiteral, StringLiteral, ArrayLiteral, HashLiteral, SymbolLiteral, ConditionalNegation, ConditionalBranch, StatementDeletion, MethodBodyReplacement, NegationInsertion, ReturnValueRemoval, CollectionReplacement
+- **Prism-based AST parsing** with source-level surgery via byte offsets
+- **Fork-based isolation** for safe mutation execution
+- **RSpec integration** for test execution
+- **Parallel execution** with configurable worker count (`--jobs`)
+- **Diff-based targeting** to mutate only changed code (`--diff HEAD~1`)
+- **Coverage-based filtering** — skip mutations on lines no test exercises
+- **JSON output** for AI agents and CI pipelines (`--format json`)
+- **CLI output** with human-readable mutation testing results
+- **Actionable suggestions** for surviving mutants
+- **Configuration file** support (`.evilution.yml`)
+- **`evilution init`** command to generate default config
+- **Error handling** with clean exit codes (0=pass, 1=fail, 2=error)

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,10 @@
+# Code of Conduct
+
+"evilution" follows [The Ruby Community Conduct Guideline](https://www.ruby-lang.org/en/conduct) in all "collaborative space", which is defined as community communications channels (such as mailing lists, submitted patches, commit comments, etc.):
+
+* Participants will be tolerant of opposing views.
+* Participants must ensure that their language and actions are free of personal attacks and disparaging personal remarks.
+* When interpreting the words and actions of others, participants should always assume good intentions.
+* Behaviour which can be reasonably considered harassment will not be tolerated.
+
+If you have any concerns about behaviour within this project, please contact us at ["denis.kiselyov@gmail.com"](mailto:"denis.kiselyov@gmail.com").

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Denis Kiselev
+
+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,190 @@
+# Evilution — Mutation Testing for Ruby
+
+> **Purpose**: Validate test suite quality by injecting small code changes (mutations) and checking whether tests detect them. Surviving mutations indicate gaps in test coverage.
+
+**License**: MIT (free, no commercial restrictions)
+**Language**: Ruby >= 3.3
+**Parser**: Prism (Ruby's official AST parser, ships with Ruby 3.3+)
+**Test framework**: RSpec (currently the only supported integration)
+
+## Installation
+
+Add to `Gemfile`:
+
+```ruby
+gem "evilution", group: :test
+```
+
+Then: `bundle install`
+
+Or standalone: `gem install evilution`
+
+## Command Reference
+
+```
+evilution [command] [options] [files...]
+```
+
+### Commands
+
+| Command   | Description                              | Default |
+|-----------|------------------------------------------|---------|
+| `run`     | Execute mutation testing against files   | Yes     |
+| `init`    | Generate `.evilution.yml` config file    |         |
+| `version` | Print version string                     |         |
+
+### Options (for `run` command)
+
+| Flag                    | Type    | Default      | Description                                       |
+|-------------------------|---------|--------------|---------------------------------------------------|
+| `-j`, `--jobs N`        | Integer | CPU cores    | Parallel worker count. Use `1` for sequential.    |
+| `-t`, `--timeout N`     | Integer | 10           | Per-mutation timeout in seconds.                   |
+| `-f`, `--format FORMAT` | String  | `text`       | Output format: `text` or `json`.                  |
+| `--diff BASE`           | String  | _(none)_     | Git ref. Only mutate methods whose definition line changed since BASE. |
+| `--min-score FLOAT`     | Float   | 0.0          | Minimum mutation score (0.0–1.0) to pass.         |
+| `--no-coverage`         | Boolean | false        | Reserved; currently has no effect.                |
+| `-v`, `--verbose`       | Boolean | false        | Verbose output.                                    |
+| `-q`, `--quiet`         | Boolean | false        | Suppress output.                                   |
+
+### Exit Codes
+
+| Code | Meaning                                       | Agent action                          |
+|------|-----------------------------------------------|---------------------------------------|
+| 0    | Mutation score meets or exceeds `--min-score` | Success. No action needed.            |
+| 1    | Mutation score below `--min-score`            | Parse output, fix surviving mutants.  |
+| 2    | Tool error (bad config, parse failure, etc.)  | Check stderr, fix invocation.         |
+
+## Configuration
+
+Generate default config: `bundle exec evilution init`
+
+Creates `.evilution.yml`:
+
+```yaml
+# jobs: 4            # parallel workers
+# timeout: 10        # seconds per mutation
+# format: text       # text | json
+# min_score: 0.0     # 0.0–1.0
+# integration: rspec # test framework
+# coverage: true     # skip mutations on uncovered lines
+```
+
+**Precedence**: CLI flags override `.evilution.yml` values.
+
+## JSON Output Schema
+
+Use `--format json` for machine-readable output. Schema:
+
+```json
+{
+  "version": "string   — gem version",
+  "timestamp": "string — ISO 8601 timestamp of the report",
+  "summary": {
+    "total": "integer    — total mutations generated",
+    "killed": "integer   — mutations detected by tests (test failed = good)",
+    "survived": "integer — mutations NOT detected (test passed = gap in coverage)",
+    "timed_out": "integer — mutations that exceeded timeout",
+    "errors": "integer   — mutations that caused unexpected errors",
+    "score": "float      — killed / (total - errors), range 0.0-1.0, rounded to 4 decimals",
+    "duration": "float   — total wall-clock seconds, rounded to 4 decimals"
+  },
+  "survived": [
+    {
+      "operator": "string — mutation operator name (see Operators table)",
+      "file": "string    — relative path to mutated file",
+      "line": "integer   — line number of the mutation",
+      "status": "string  — result status: 'survived', 'killed', 'timeout', or 'error'",
+      "duration": "float — seconds this mutation took, rounded to 4 decimals",
+      "diff": "string    — unified diff snippet",
+      "suggestion": "string — actionable hint for surviving mutants (survived only)"
+    }
+  ],
+  "killed": ["... same shape as survived entries ..."],
+  "timed_out": ["... same shape as survived entries ..."],
+  "errors": ["... same shape as survived entries ..."]
+}
+```
+
+**Key metric**: `summary.score` — the mutation score. Higher is better. 1.0 means all mutations were caught.
+
+## Mutation Operators (18 total)
+
+Each operator name is stable and appears in JSON output under `survived[].operator`.
+
+| Operator                  | What it does                              | Example                            |
+|---------------------------|-------------------------------------------|------------------------------------|
+| `arithmetic_replacement`  | Swap arithmetic operators                 | `a + b` -> `a - b`                |
+| `comparison_replacement`  | Swap comparison operators                 | `a >= b` -> `a > b`               |
+| `boolean_operator_replacement` | Swap `&&` / `\|\|`                   | `a && b` -> `a \|\| b`            |
+| `boolean_literal_replacement`  | Flip boolean literals                 | `true` -> `false`                  |
+| `nil_replacement`         | Replace expression with `nil`             | `expr` -> `nil`                    |
+| `integer_literal`         | Boundary-value integer mutations          | `n` -> `0`, `1`, `n+1`, `n-1`     |
+| `float_literal`           | Boundary-value float mutations            | `f` -> `0.0`, `1.0`               |
+| `string_literal`          | Empty the string                          | `"str"` -> `""`                    |
+| `array_literal`           | Empty the array                           | `[a, b]` -> `[]`                   |
+| `hash_literal`            | Empty the hash                            | `{k: v}` -> `{}`                  |
+| `symbol_literal`          | Replace with sentinel symbol              | `:foo` -> `:__evilution_mutated__` |
+| `conditional_negation`    | Replace condition with `true`/`false`     | `if cond` -> `if true`            |
+| `conditional_branch`      | Remove if/else branch                     | Deletes branch body                |
+| `statement_deletion`      | Remove statements from method bodies      | Deletes a statement                |
+| `method_body_replacement` | Replace entire method body with `nil`     | Method body -> `nil`               |
+| `negation_insertion`      | Negate predicate methods                  | `x.empty?` -> `!x.empty?`         |
+| `return_value_removal`    | Strip return values                       | `return x` -> `return`            |
+| `collection_replacement`  | Swap collection methods                   | `map` -> `each`, `select` <-> `reject` |
+
+## Recommended Workflows for AI Agents
+
+### 1. Full project scan
+
+```bash
+bundle exec evilution run lib/ --format json --jobs 4 --min-score 0.8
+```
+
+Parse JSON output. Exit code 0 = pass, 1 = surviving mutants to address.
+
+### 2. PR / diff-only scan (fast feedback)
+
+```bash
+bundle exec evilution run lib/ --format json --diff main --min-score 0.9
+```
+
+Mutates methods whose definition (starting) line is changed compared to `main` (the diff filter is based on the method’s first line, not any line in its body). Use this for incremental checks — it's fast and focused on newly added or moved methods and changed signatures.
+
+### 3. Single-file targeted scan
+
+```bash
+bundle exec evilution run lib/specific_file.rb --format json
+```
+
+Use when you know which file was modified and want to verify its test coverage.
+
+### 4. Fixing surviving mutants
+
+For each entry in `survived[]`:
+1. Read `file` at `line` to understand the code context
+2. Read `operator` to understand what was changed
+3. Read `suggestion` for a hint on what test to write
+4. Write a test that would fail if the mutation were applied
+5. Re-run evilution on just that file to verify the mutant is now killed
+
+### 5. CI gate
+
+```bash
+bundle exec evilution run lib/ --format json --min-score 0.8 --quiet
+# Exit code 0 = pass, 1 = fail, 2 = error
+```
+
+Note: `--quiet` suppresses all stdout output (including JSON). Use it in CI only when you care about the exit code and do not need JSON output.
+
+## Internals (for context, not for direct use)
+
+1. **Parse** — Prism parses Ruby files into ASTs with exact byte offsets
+2. **Extract** — Methods are identified as mutation subjects
+3. **Mutate** — Operators produce text replacements at precise byte offsets (source-level surgery, no AST unparsing)
+4. **Isolate** — Each mutation runs in a `fork()`-ed child process (no test pollution)
+5. **Test** — RSpec executes against the mutated source
+6. **Report** — Results aggregated into text or JSON
+
+## Repository
+
+https://github.com/marinazzio/evilution

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/claude-swarm.yml

@@ -0,0 +1,28 @@
+version: 1
+swarm:
+  name: "Evilution Ruby gem Development Team"
+  main: architect
+
+  instances:
+    architect:
+      description: "Ruby architect coordinating full-stack development for Evilution Ruby gem"
+      directory: .
+      model: opus
+      connections: [tests, devops]
+      prompt_file: .claude/prompts/architect.md
+      vibe: true
+
+    tests:
+      description: "RSpec testing, factories, and test coverage specialist"
+      directory: ./spec
+      model: opus
+      allowed_tools: [Read, Edit, Write, Bash, Grep, Glob, LS]
+      prompt_file: .claude/prompts/tests.md
+
+    
+    devops:
+      description: "Deployment, Docker, CI/CD, and production configuration specialist"
+      directory: ./.github
+      model: opus
+      allowed_tools: [Read, Edit, Write, Bash, Grep, Glob, LS]
+      prompt_file: .claude/prompts/devops.md

data/exe/evilution

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "evilution"
+
+exit Evilution::CLI.new(ARGV).call

data/lib/evilution/ast/parser.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+require "prism"
+
+module Evilution
+  module AST
+    class Parser
+      def call(file_path)
+        raise ParseError, "file not found: #{file_path}" unless File.exist?(file_path)
+
+        source = File.read(file_path)
+        result = Prism.parse(source)
+
+        raise ParseError, "failed to parse #{file_path}: #{result.errors.map(&:message).join(", ")}" if result.failure?
+
+        extract_subjects(result.value, source, file_path)
+      end
+
+      private
+
+      def extract_subjects(tree, source, file_path)
+        finder = SubjectFinder.new(source, file_path)
+        finder.visit(tree)
+        finder.subjects
+      end
+    end
+
+    class SubjectFinder < Prism::Visitor
+      attr_reader :subjects
+
+      def initialize(source, file_path)
+        @source = source
+        @file_path = file_path
+        @subjects = []
+        @context = []
+      end
+
+      def visit_module_node(node)
+        @context.push(constant_name(node.constant_path))
+        super
+        @context.pop
+      end
+
+      def visit_class_node(node)
+        @context.push(constant_name(node.constant_path))
+        super
+        @context.pop
+      end
+
+      def visit_def_node(node)
+        scope = @context.join("::")
+        name = if scope.empty?
+                 "##{node.name}"
+               else
+                 "#{scope}##{node.name}"
+               end
+
+        loc = node.location
+        method_source = @source[loc.start_offset...loc.end_offset]
+
+        @subjects << Subject.new(
+          name: name,
+          file_path: @file_path,
+          line_number: loc.start_line,
+          source: method_source,
+          node: node
+        )
+
+        super
+      end
+
+      private
+
+      def constant_name(node)
+        if node.respond_to?(:full_name)
+          node.full_name
+        else
+          node.name.to_s
+        end
+      end
+    end
+  end
+end

data/lib/evilution/ast/source_surgeon.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Evilution
+  module AST
+    module SourceSurgeon
+      def self.apply(source, offset:, length:, replacement:)
+        result = source.dup
+        result[offset, length] = replacement
+        result
+      end
+    end
+  end
+end