henitai 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 586e777c1eb78b5345eedde4f010ab262fe1ced6e0ac3714e21dbd9aa7cc63d3
+  data.tar.gz: 7d6d5d3939777b28ab127133dc4f2d9663c29c812f6f4a77af4705a3f36ef973
+SHA512:
+  metadata.gz: 0fd445f2506b0dec762413e3e992af6b93797728c4253a86de2e1ce0f60fcd189ac2d2f342033ac8d16653064ce3fc3cd885c69ad34026e9781c60ca88d85de4
+  data.tar.gz: 9d00b7d9f3237b70460306aae62729d38e0142fbf7b954c2b4528feda3a4e596f08bd373c9ed448fd0ff12de7c5c1fb867c3ea9f8cf8582792a9c3a454d2bfd5

data/CHANGELOG.md

@@ -0,0 +1,19 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+- Initial gem scaffold with Ruby 4.0.2 support
+- Dev Container configuration (official `ruby:4.0.2-alpine` base image, Codex CLI preinstalled)
+- CI pipeline (RuboCop + RSpec + incremental mutation testing on PRs)
+- `.henitai.yml` configuration schema
+- Module structure: `Configuration`, `Subject`, `Mutant`, `Operator`, `Runner`, `Reporter`, `Integration`, `Result`
+- CLI critical path: `henitai run` now executes the full pipeline, supports `--since`, returns CI-friendly exit codes, and `henitai version` prints `Henitai::VERSION`
+- RSpec per-test coverage output: `henitai/coverage_formatter` now writes `coverage/henitai_per_test.json`
+
+[Unreleased]: https://github.com/martinotten/henitai/commits/main

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Martin Otten
+
+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,182 @@
+# hen’itai
+
+変異体 (へんいたい, hen’itai)
+Pronunciation: he-n-i-ta-i (4 morae; no stress accent)
+Meaning: mutant, mutated organism, or variant entity
+
+
+A Ruby mutation testing framework
+
+[![CI](https://github.com/martinotten/henitai/actions/workflows/ci.yml/badge.svg)](https://github.com/martinotten/henitai/actions/workflows/ci.yml)
+[![Gem Version](https://badge.fury.io/rb/henitai.svg)](https://badge.fury.io/rb/henitai)
+
+---
+
+## Maturaty
+
+- This is alpha software, there will be bugs
+- Henitai tests itself
+- Stryker Dashboard support is untested
+- Minitest support is untested
+- Lots of code has been carefully crafted by AI agents, not everything has been reviewed by humans (yet)
+
+## What is mutation testing?
+
+Mutation testing answers the question that code coverage cannot: **does your test suite actually verify the behaviour of your code?**
+
+A mutation testing tool makes small, systematic changes — *mutants* — to your source code (e.g. replacing `>` with `>=`, removing a `return` statement, flipping a boolean) and then runs your tests. A mutant that causes at least one test to fail is *killed*. A mutant that passes all tests is *survived* — evidence that your tests are not covering that behaviour.
+
+The ratio of killed mutants to total mutants is the **Mutation Score** (MS). A high mutation score is a strong quality signal.
+
+## Installation
+
+Add to your `Gemfile`:
+
+```ruby
+gem "henitai", group: :development
+```
+
+Or install globally:
+
+```sh
+gem install henitai
+```
+
+**Requires Ruby 4.0.2+**
+
+## Quick start
+
+```sh
+# Run mutation testing on the entire project
+bundle exec henitai run
+
+# Run only on subjects changed since main (CI-friendly)
+bundle exec henitai run --since origin/main
+
+# Run on a specific subject pattern
+bundle exec henitai run 'MyClass#my_method'
+bundle exec henitai run 'MyNamespace*'
+```
+
+Configuration lives in `.henitai.yml`:
+
+```yaml
+# yaml-language-server: $schema=./assets/schema/henitai.schema.json
+integration:
+  name: rspec
+
+includes:
+  - lib
+
+mutation:
+  operators: light   # light | full
+  timeout: 10.0
+  max_mutants_per_line: 1
+  max_flaky_retries: 3
+  sampling:
+    ratio: 0.05
+    strategy: stratified
+reports_dir: reports
+
+thresholds:
+  high: 80
+  low: 60
+```
+
+Henitai warns on unknown config keys and aborts with `Henitai::ConfigurationError`
+when a value is invalid.
+
+CLI flags override the corresponding values from `.henitai.yml`.
+
+Before mutation testing starts, Henitai checks whether the current coverage data
+covers the configured source files. If not, Henitai runs the configured test
+suite once to bootstrap a usable coverage baseline. If coverage is still
+unavailable for the current sources, `henitai run` aborts with
+`Henitai::CoverageError`.
+
+Surviving mutants are retried up to `mutation.max_flaky_retries` times before
+they are classified as survivors. The default retry budget is 3.
+
+Per-test coverage reporting is currently wired through the RSpec child runner.
+Minitest integration reuses the same selection and execution flow, but does not
+yet enable the per-test coverage formatter.
+
+By default, Henitai keeps child test output out of the live terminal. Each
+baseline or mutant run writes captured stdout/stderr to `reports/mutation-logs/`
+and the terminal only shows progress plus a concise summary. Pass
+`--all-logs` (or `--verbose`) to print every captured child log.
+
+`henitai version` prints the installed version. `henitai run` exits with `0`
+when the mutation score meets the low threshold, `1` when it does not, and `2`
+for framework errors.
+
+The repository ships a JSON Schema at [`assets/schema/henitai.schema.json`](/workspaces/henitai/assets/schema/henitai.schema.json) for editor autocompletion.
+
+## Operator sets
+
+**Light** (default) — high-signal, low-noise operators covering the majority of real-world defects:
+
+- `ArithmeticOperator` — `+` ↔ `-`, `*` ↔ `/`
+- `EqualityOperator` — `==` ↔ `!=`, `>` ↔ `<`, etc.
+- `LogicalOperator` — `&&` ↔ `||`
+- `BooleanLiteral` — `true` ↔ `false`, `!expr`
+- `ConditionalExpression` — remove branch bodies
+- `StringLiteral` — empty string replacement
+- `ReturnValue` — mutate return expressions
+
+**Full** — adds lower-signal operators:
+
+- `ArrayDeclaration`, `HashLiteral`, `RangeLiteral`
+- `SafeNavigation` — `&.` → `.`
+- `PatternMatch` — case/in arm removal
+- `BlockStatement` — remove blocks
+- `MethodExpression` — remove calls
+- `AssignmentExpression` — mutate compound assignment
+
+## Stryker Dashboard integration (untested)
+
+```yaml
+# .henitai.yml
+reporters:
+  - terminal
+  - html
+  - json
+  - dashboard
+
+dashboard:
+  project: "github.com/your-org/your-repo"
+  base_url: "https://dashboard.stryker-mutator.io"
+```
+
+Set `STRYKER_DASHBOARD_API_KEY` in your CI environment to publish reports.
+
+JSON reports are written to `reports/mutation-report.json` by default. Set
+`reports_dir` to change the output directory.
+
+## Development
+
+```sh
+git clone https://github.com/martinotten/henitai
+cd henitai
+bundle install
+bundle exec rspec        # run tests
+bundle exec rubocop      # lint
+bundle exec henitai run  # dogfood
+```
+
+A Dev Container configuration is included (`.devcontainer/`) for VS Code with the official `ruby:4.0.2-alpine` image and the Codex CLI preinstalled.
+
+## Architecture
+
+See [`docs/architecture/architecture.md`](docs/architecture/architecture.md) for the full design document, including:
+
+- Phase-Gate pipeline (5 gates)
+- AST-based operator implementation
+- Fork isolation model
+- Stryker JSON schema integration
+- Architecture decisions in [`docs/architecture/adr/`](docs/architecture/adr/)
+- Three-phase roadmap
+
+## License
+
+[MIT License](LICENSE) — © 2026 Martin Otten

data/assets/schema/henitai.schema.json

@@ -0,0 +1,123 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://github.com/martinotten/henitai/assets/schema/henitai.schema.json",
+  "title": "Henitai configuration",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "integration": {
+      "oneOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "name": {
+              "type": "string"
+            }
+          }
+        }
+      ]
+    },
+    "includes": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "mutation": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "operators": {
+          "enum": ["light", "full"]
+        },
+        "timeout": {
+          "type": "number"
+        },
+        "max_mutants_per_line": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "max_flaky_retries": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "ignore_patterns": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "sampling": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["ratio", "strategy"],
+          "properties": {
+            "ratio": {
+              "type": "number",
+              "minimum": 0,
+              "maximum": 1
+            },
+            "strategy": {
+              "enum": ["stratified"]
+            }
+          }
+        }
+      }
+    },
+    "coverage_criteria": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "test_result": {
+          "type": "boolean"
+        },
+        "timeout": {
+          "type": "boolean"
+        },
+        "process_abort": {
+          "type": "boolean"
+        }
+      }
+    },
+    "thresholds": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "high": {
+          "type": "integer"
+        },
+        "low": {
+          "type": "integer"
+        }
+      }
+    },
+    "reporters": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "reports_dir": {
+      "type": "string"
+    },
+    "dashboard": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "project": {
+          "type": "string"
+        },
+        "base_url": {
+          "type": "string"
+        }
+      }
+    },
+    "jobs": {
+      "type": ["integer", "null"]
+    }
+  }
+}

data/exe/henitai

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "henitai"
+
+Henitai::CLI.start(ARGV)

data/lib/henitai/arid_node_filter.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+module Henitai
+  # Suppresses AST nodes that are unlikely to produce useful mutants.
+  class AridNodeFilter
+    DIRECT_OUTPUT_METHODS = %i[puts p pp warn].freeze
+    DIRECT_DEBUG_METHODS = %i[byebug debugger].freeze
+    BINDING_DEBUG_METHODS = %i[pry].freeze
+    LOGGER_METHODS = %i[debug info warn error fatal].freeze
+    INVARIANT_METHODS = %i[is_a? respond_to? kind_of?].freeze
+    DSL_METHODS = %i[let subject before after].freeze
+
+    def suppressed?(node, config)
+      custom_pattern_match?(node, config) || catalog_match?(node)
+    end
+
+    private
+
+    def custom_pattern_match?(node, config)
+      source = node.location&.expression&.source
+      return false unless source
+
+      compiled_ignore_patterns(config).any? do |pattern|
+        pattern.match?(source)
+      end
+    end
+
+    def compiled_ignore_patterns(config)
+      patterns = Array(config&.ignore_patterns).dup.freeze
+      @compiled_ignore_patterns ||= {}
+      @compiled_ignore_patterns[patterns] ||= patterns.map { |pattern| Regexp.new(pattern) }
+    end
+
+    def catalog_match?(node)
+      case node.type
+      when :send
+        send_match?(node)
+      when :block
+        block_match?(node)
+      when :or_asgn
+        true
+      else
+        false
+      end
+    end
+
+    def send_match?(node)
+      receiver, method_name, = node.children
+      method_name = method_name&.to_sym
+
+      return true if direct_output_call?(receiver, method_name)
+      return true if direct_debug_call?(receiver, method_name)
+      return true if binding_debug_call?(receiver, method_name)
+      return true if rails_logger_call?(receiver, method_name)
+
+      invariant_call?(method_name)
+    end
+
+    def block_match?(node)
+      send_node = node.children.first
+      return false unless send_node&.type == :send
+
+      receiver, method_name, = send_node.children
+      receiver.nil? && DSL_METHODS.include?(method_name.to_sym)
+    end
+
+    def direct_output_call?(receiver, method_name)
+      receiver.nil? && DIRECT_OUTPUT_METHODS.include?(method_name)
+    end
+
+    def direct_debug_call?(receiver, method_name)
+      receiver.nil? && DIRECT_DEBUG_METHODS.include?(method_name)
+    end
+
+    def binding_debug_call?(receiver, method_name)
+      send_call?(receiver, :binding) && BINDING_DEBUG_METHODS.include?(method_name)
+    end
+
+    def rails_logger_call?(receiver, method_name)
+      logger_receiver?(receiver) && LOGGER_METHODS.include?(method_name)
+    end
+
+    def invariant_call?(method_name)
+      INVARIANT_METHODS.include?(method_name)
+    end
+
+    def logger_receiver?(node)
+      send_call?(node, :logger) &&
+        node.children.first&.type == :const &&
+        node.children.first.children.last == :Rails
+    end
+
+    def send_call?(node, method_name)
+      node&.type == :send && node.children[1] == method_name
+    end
+  end
+end