henitai 0.1.10 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a993f2073367de6b25c8fe922a2089f57103d79790c1e9cd95d2ba6b573b3050
-  data.tar.gz: d6956c7b23f1ec7cd97773cdd249a2c12b17f75e080cb98092d34049a763c607
+  metadata.gz: cda194514bf677d142e24c97c1589714041d2c88c4d2b33ffaf642e79c7ebe5d
+  data.tar.gz: 8505d5d6add5b850c5accb4904f43351e129b9261699c58051c35faa1a4b3758
 SHA512:
-  metadata.gz: e7a1925ad77b77ac4ed802b3419b15988a436098488a2dfb0ee11f8f930da024bc05a686606ae4e86ba6fd9f36ef4aed19ef8b1e46bef31e143d25ee4dc54ded
-  data.tar.gz: f095d945bd5f9313a202db7a6ce3936a69233b47d62b92ec353950857c27d58b75dc8084164383d66558ef2a076c62e2fd53e68621d8b9d95546c6b1114faa73
+  metadata.gz: b17e21c51f0d4aac03154d8b782d4e361ea8fa792c03a984b9d5b94deccd2411ffb3fe8a7e6fe096b76b33f2bc211a813618c059642b4dec3e54b8fab4d01d8a
+  data.tar.gz: 109527f73b390086f03b5249dd90e97bf57ad3e34551f94d1f80b8f1e5968699e8d6cefe394ebf87bc10465b2a759de737d5f54257807e654a92cd040fa73f59

data/CHANGELOG.md

@@ -7,6 +7,97 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.2.1] - 2026-06-25
+
+### Fixed
+- `henitai run` now exits 0 when a run evaluates no valid mutants, instead of
+  failing a CI gate on a vacuous result
+- Flaky-retry counts are now recorded on the parallel execution path (they were
+  always reported as 0 regardless of actual retries)
+
+### Changed
+- `Result` and `Reporter::Json` take their IO as an injected dependency,
+  restoring the domain/infrastructure boundary (no public API change)
+- Decomposed the monolithic `integration.rb` into single-responsibility files
+  and reparented `Integration::Minitest` off `Rspec` onto a shared
+  `MutantRunSupport` mixin; restored class-size discipline across the codebase
+- Narrowed broad rescues in `safe_unparse` and per-test coverage snapshotting
+
+### Internal
+- De-mocked runner specs, added `process_wakeup` and helper coverage, and
+  removed sleep- and chdir-based flakiness from the suite
+- Enabled full-operator dogfooding configuration and isolated the
+  `minitest_simplecov` spec
+- Reconciled README and consolidated plan-tree documentation
+
+## [0.2.0] - 2026-04-30
+
+### Added
+- `--survivors-from <path>` flag on `henitai run` for survivor-only reruns:
+  re-execute only the mutants that survived a prior full run without re-running
+  the whole suite
+- `SurvivorLoader` reads a Stryker-compatible JSON report and extracts survivor
+  IDs, per-survivor coverage maps (`coveredBy`), and the anchoring git SHA
+- `SurvivorSelector` filters the current mutant set to the survivor subset; emits
+  a drift warning when more than 50% of loaded survivors are unmatched (source
+  changed significantly since the prior run)
+- `SurvivorTestFilter` skips survivors whose covering tests are unchanged since
+  the prior report's git SHA, marking them `:survived` immediately without
+  execution — same safety logic as StrykerJS incremental mode
+- `MutantIdentity` module: stable SHA256 identity computed from expression,
+  operator, description, location, and mutation signature; shared by
+  `MutantHistoryStore` and `Mutant#stable_id`
+- `Mutant#stable_id` exposes the stable identity; emitted as `stableId` in the
+  JSON report so survivor reports remain useful across commits
+- `Result` carries `session_id` (UUID) and optional `git_sha` (HEAD SHA at
+  report time); both emitted in the Stryker-compatible JSON as `sessionId` /
+  `gitSha`
+- `Reporter::Json` writes an immutable per-session snapshot alongside the
+  canonical report at `reports/sessions/<session_id>/mutation-report.json`,
+  giving `--survivors-from` a stable reference path across runs
+- `GitDiffAnalyzer#head_sha` — returns the current HEAD SHA; `nil` when git is
+  unavailable (conservative fallback: all survivors are executed)
+- `ProcessWorkerRunner` — flat process-slot scheduler for parallel mutant
+  execution: each slot owns one OS process, slots are refilled as children
+  finish, no thread per child
+- Interrupt handling, spawn failure isolation, and in-slot retry added to
+  `ProcessWorkerRunner` (PR 6)
+- Timeout precision and two-phase process-group cleanup in
+  `ProcessWorkerRunner` (PR 5)
+- x86_64 platform added to gem platform list
+
+### Changed
+- JSON mutation report vendor extension now always includes `sessionId`
+  (and `gitSha` when available) to support survivor-only reruns
+- Terminal reporter labels partial reruns as "Partial survivor rerun" and
+  shows matched / unmatched / skipped-by-diff counts
+- History store skips `runs` row insertion for partial reruns to avoid
+  distorting trend analytics; per-mutant `current_status` upsert still runs
+- CLI exits 0 for partial reruns with a printed warning; threshold comparison
+  is skipped (applying a partial score to a CI gate is misleading)
+- `StaticFilter` merges per-test coverage into standard coverage so
+  `coveredBy` data is available to both RSpec and Minitest survivor reports
+- `.henitai.yml` default: operators set to `light`, timeout lowered to 10 s,
+  `max_flaky_retries: 3` added
+
+### Fixed
+- Minitest autorun hook suppressed in mutation child processes to prevent
+  spurious re-runs of the full suite inside each fork
+- Coverage bootstrap RSpec subprocess ARGV leakage resolved — child processes
+  no longer inherit the parent's `--format` / file arguments
+- Survivor rerun state preserved across RSpec execution (was reset on each
+  subprocess boot)
+- `--survivors-from` now respects dirty worktrees: coverage and source file
+  state are read from the working tree, not the index
+- Recipe fast path skipped when source files changed since the cached run,
+  preventing stale cache hits after edits
+
+### Performance
+- File discovery cached in the integration layer; repeated calls within one
+  run no longer re-scan the filesystem
+- Polling sleep removed from the scheduler hot loop; slots are refilled
+  event-driven on child exit
+
 ## [0.1.10] - 2026-04-16
 
 ### Fixed
@@ -211,7 +302,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - 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/compare/v0.1.10...HEAD
+[Unreleased]: https://github.com/martinotten/henitai/compare/v0.2.1...HEAD
+[0.2.1]: https://github.com/martinotten/henitai/compare/v0.2.0...v0.2.1
+[0.2.0]: https://github.com/martinotten/henitai/compare/v0.1.10...v0.2.0
 [0.1.10]: https://github.com/martinotten/henitai/compare/v0.1.9...v0.1.10
 [0.1.9]: https://github.com/martinotten/henitai/compare/v0.1.8...v0.1.9
 [0.1.8]: https://github.com/martinotten/henitai/compare/v0.1.7...v0.1.8

data/README.md

@@ -15,10 +15,9 @@ A Ruby mutation testing framework
 ## 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)
+- Henitai tests itself and other projects
+- It might break with a release
+- If you need a mature solution for mutation testing in ruby, take a look at the [https://github.com/mbj/mutant](Mutant gem)
 
 ## What is mutation testing?
 
@@ -28,6 +27,8 @@ A mutation testing tool makes small, systematic changes — *mutants* — to you
 
 The ratio of killed mutants to total mutants is the **Mutation Score** (MS). A high mutation score is a strong quality signal.
 
+As mutation testing modifies your code you make sure that your tests cannot have any unintended side-effects.
+
 ## Installation
 
 Add to your `Gemfile`:
@@ -42,7 +43,7 @@ Or install globally:
 gem install henitai
 ```
 
-**Requires Ruby 4.0.2+**
+**Requires Ruby 4.0.0+**
 
 ## Quick start
 
@@ -56,6 +57,9 @@ 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*'
+
+# Re-run only survivors from a prior mutation report
+bundle exec henitai run --survivors-from reports/mutation-report.json
 ```
 
 Configuration lives in `.henitai.yml`:
@@ -68,6 +72,9 @@ integration:
 includes:
   - lib
 
+excludes:
+  - lib/henitai/eager_load.rb   # standalone entry points with no in-process coverage
+
 mutation:
   operators: light   # light | full
   timeout: 10.0
@@ -112,6 +119,12 @@ and the terminal only shows progress plus a concise summary. Pass
 when the mutation score meets the low threshold, `1` when it does not, and `2`
 for framework errors.
 
+`henitai run --survivors-from ...` performs a partial rerun: it reports only
+the selected survivors, skips threshold-based exit checks, and does not update
+the run trend history. Dirty worktree changes are included, so you can edit
+tests locally without committing first; if source files under `includes` are
+dirty, Henitai reruns the matched survivors conservatively.
+
 The repository ships a JSON Schema at [`assets/schema/henitai.schema.json`](/workspaces/henitai/assets/schema/henitai.schema.json) for editor autocompletion.
 
 ## Operator sets
@@ -129,13 +142,17 @@ The repository ships a JSON Schema at [`assets/schema/henitai.schema.json`](/wor
 **Full** — adds lower-signal operators:
 
 - `ArrayDeclaration`, `HashLiteral`, `RangeLiteral`
+- `MethodChainUnwrap` — remove a link from a method chain
+- `RegexMutator` — mutate regexp quantifiers, anchors, char-class negation
 - `SafeNavigation` — `&.` → `.`
 - `PatternMatch` — case/in arm removal
 - `BlockStatement` — remove blocks
 - `MethodExpression` — remove calls
 - `AssignmentExpression` — mutate compound assignment
+- `UnaryOperator` — remove unary `-` and `~`
+- `UpdateOperator` — swap compound assignments (`+=`↔`-=`, `*=`↔`/=`, `||=`↔`&&=`)
 
-## Stryker Dashboard integration (untested)
+## Stryker Dashboard integration
 
 ```yaml
 # .henitai.yml
@@ -150,7 +167,12 @@ dashboard:
   base_url: "https://dashboard.stryker-mutator.io"
 ```
 
-Set `STRYKER_DASHBOARD_API_KEY` in your CI environment to publish reports.
+Set `STRYKER_DASHBOARD_API_KEY` in your CI environment to publish reports. When
+the key, project, and version are present, the `dashboard` reporter uploads the
+Stryker-schema report to the dashboard REST API (default
+`https://dashboard.stryker-mutator.io`); otherwise it is skipped silently. The
+project defaults to the git remote and the version to the current branch or CI
+ref (`GITHUB_REF_NAME`/`GITHUB_REF`/`GITHUB_SHA`).
 
 JSON reports are written to `reports/mutation-report.json` by default. Set
 `reports_dir` to change the output directory.
@@ -172,6 +194,10 @@ Framework integration smoke projects live under `spec/fixtures/integration_smoke
 and exercise `henitai` against small RSpec and Minitest apps via the local path
 dependency.
 
+Git hook support is tracked in [`.githooks/pre-commit`](/Users/martinotten/projects/mo/henitai/.githooks/pre-commit).
+Enable it with `git config core.hooksPath .githooks` so commits run RuboCop,
+RSpec, and the integration smoke suite before they are created.
+
 A Dev Container configuration is included (`.devcontainer/`) for VS Code with the official `ruby:4`
 image, the Codex CLI, and RTK preinstalled. Codex support is bootstrapped with
 `rtk init -g --codex --auto-patch` during container creation.

data/assets/schema/henitai.schema.json

@@ -27,6 +27,12 @@
         "type": "string"
       }
     },
+    "excludes": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
     "mutation": {
       "type": "object",
       "additionalProperties": false,

data/lib/henitai/cli/clean_command.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module Henitai
+  class CLI
+    # Implements `henitai clean`: removes generated report artifacts listed in
+    # {CLI::REPORT_CLEANUP_PATHS} and prints a deletion summary. Mixed into
+    # {CLI}.
+    module CleanCommand
+      private
+
+      def clean_command
+        @command_halted = false
+        options = parse_clean_options
+        return if @command_halted
+
+        config = load_config(options)
+        removed_paths = cleanup_report_artifacts(config)
+        puts clean_summary(removed_paths)
+      rescue StandardError => e
+        handle_run_error(e)
+      end
+
+      def cleanup_report_artifacts(config)
+        removed_paths = report_cleanup_paths(config).select { |path| File.exist?(path) }
+        removed_paths.each { |path| FileUtils.rm_f(path) }
+        removed_paths
+      end
+
+      def report_cleanup_paths(config)
+        REPORT_CLEANUP_PATHS.map do |relative_path|
+          File.join(config.reports_dir, *relative_path)
+        end
+      end
+
+      def clean_summary(removed_paths)
+        return "No generated report artifacts to clean" if removed_paths.empty?
+
+        format(
+          "Removed %<count>s generated report artifact%<plural>s",
+          count: removed_paths.length,
+          plural: removed_paths.length == 1 ? "" : "s"
+        )
+      end
+    end
+  end
+end

data/lib/henitai/cli/command_support.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Henitai
+  class CLI
+    # Shared helpers for CLI command handlers: configuration loading (applying
+    # CLI overrides on top of the config file) and uniform error handling.
+    module CommandSupport
+      private
+
+      def load_config(options)
+        Configuration.load(
+          path: options.fetch(:config, Configuration::CONFIG_FILE),
+          overrides: configuration_overrides(options)
+        )
+      end
+
+      def configuration_overrides(options)
+        deep_compact(
+          {
+            integration: options[:integration],
+            all_logs: options[:all_logs],
+            mutation: {
+              operators: options[:operators],
+              timeout: options[:timeout]
+            },
+            jobs: options[:jobs]
+          }
+        )
+      end
+
+      def deep_compact(value)
+        case value
+        when Hash
+          value.each_with_object({}) do |(key, nested_value), result|
+            compacted = deep_compact(nested_value)
+            result[key] = compacted unless compacted.nil?
+          end
+        when Array
+          value.map { |item| deep_compact(item) }.compact
+        else
+          value
+        end
+      end
+
+      def handle_run_error(error)
+        warn "#{error.class}: #{error.message}"
+        exit 2
+      end
+    end
+  end
+end

data/lib/henitai/cli/init_command.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Henitai
+  class CLI
+    # Implements `henitai init`: writes a starter `.henitai.yml`, optionally
+    # prompting for the default RSpec integration when stdin is a TTY. Mixed
+    # into {CLI}.
+    module InitCommand
+      INIT_TEMPLATE_LINES = [
+        "# yaml-language-server: $schema=./assets/schema/henitai.schema.json",
+        "includes:",
+        "  - lib",
+        "mutation:",
+        "  operators: light",
+        "  timeout: 10.0",
+        "  max_flaky_retries: 3",
+        "  sampling:",
+        "    ratio: 0.05",
+        "    strategy: stratified",
+        "reports_dir: reports",
+        "thresholds:",
+        "  high: 80",
+        "  low: 60"
+      ].freeze
+
+      private
+
+      def init_command
+        path = @argv.shift || Configuration::CONFIG_FILE
+        unexpected_arguments = @argv.dup
+        warn "Unexpected arguments: #{unexpected_arguments.join(' ')}" unless unexpected_arguments.empty?
+        exit 1 unless unexpected_arguments.empty?
+
+        File.write(path, init_template)
+        puts "Created #{path}"
+      end
+
+      def init_template
+        template = init_template_lines
+        template << integration_block if include_default_integration?
+        "#{template.join("\n")}\n"
+      end
+
+      def init_template_lines
+        INIT_TEMPLATE_LINES.dup
+      end
+
+      def include_default_integration?
+        return true unless $stdin.tty?
+
+        print "Use the default RSpec integration? [Y/n] "
+        response = $stdin.gets&.strip&.downcase
+        response.nil? || response.empty? || !%w[n no].include?(response)
+      end
+
+      def integration_block
+        <<~YAML.chomp
+          integration:
+            name: rspec
+        YAML
+      end
+    end
+  end
+end

data/lib/henitai/cli/operator_command.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+module Henitai
+  class CLI
+    # Implements `henitai operator`: lists the built-in operators with their
+    # human-readable descriptions and examples. Mixed into {CLI}.
+    module OperatorCommand
+      OPERATOR_METADATA = {
+        "ArithmeticOperator" => ["Arithmetic operators", "a + b -> a - b"],
+        "EqualityOperator" => ["Comparison operators", "a == b -> a != b"],
+        "LogicalOperator" => ["Boolean operators", "a && b -> a || b"],
+        "BooleanLiteral" => ["Boolean literals", "true -> false"],
+        "ConditionalExpression" => ["Conditional branches", "if cond then ... end"],
+        "StringLiteral" => ["String literals", '"foo" -> ""'],
+        "ReturnValue" => ["Return expressions", "return x -> return nil"],
+        "ArrayDeclaration" => ["Array literals", "[1, 2] -> []"],
+        "HashLiteral" => ["Hash literals", "{ a: 1 } -> {}"],
+        "RangeLiteral" => ["Range literals", "1..5 -> 1...5"],
+        "SafeNavigation" => ["Safe navigation", "user&.name -> user.name"],
+        "PatternMatch" => ["Pattern matching", "in { x: Integer } -> in { x: String }"],
+        "BlockStatement" => ["Block statements", "{ do_work } -> {}"],
+        "MethodExpression" => ["Method calls", "call_service -> nil"],
+        "AssignmentExpression" => ["Assignment expressions", "x += 1 -> x -= 1"],
+        "MethodChainUnwrap" => ["Method chain unwrap", "a.b.c -> a.b"],
+        "RegexMutator" => ["Regex literals", "/foo+/ -> /foo*/"],
+        "UnaryOperator" => ["Unary operators", "-x -> x"],
+        "UpdateOperator" => ["Compound assignment", "x += 1 -> x -= 1"]
+      }.freeze
+
+      private
+
+      def operator_command
+        subcommand = @argv.shift
+        case subcommand
+        when "list" then puts operator_list_text
+        when nil, "-h", "--help" then puts operator_help_text
+        else
+          warn "Unknown operator command: #{subcommand}"
+          warn operator_help_text
+          exit 1
+        end
+      rescue ArgumentError => e
+        warn e.message
+        exit 1
+      end
+
+      def operator_help_text
+        <<~HELP
+          Hen'i-tai operator commands
+
+          Usage:
+            henitai operator list
+
+          Run `henitai operator list` to see all built-in operators.
+        HELP
+      end
+
+      def operator_list_text
+        validate_operator_metadata!
+        sections = [
+          operator_list_section("Light set", Operator::LIGHT_SET),
+          operator_list_section("Full set", Operator::FULL_SET)
+        ]
+
+        ["Available operators", *sections].join("\n")
+      end
+
+      def operator_list_section(title, names)
+        rows = names.map { |name| operator_description_row(name) }
+        ([title] + rows).join("\n")
+      end
+
+      def operator_description_row(name)
+        description, example = operator_metadata[name] || fallback_operator_metadata
+
+        format("- %<name>s: %<description>s (%<example>s)", name:, description:, example:)
+      end
+
+      def operator_metadata
+        OPERATOR_METADATA
+      end
+
+      def fallback_operator_metadata
+        ["No metadata available", "n/a"]
+      end
+
+      def validate_operator_metadata!
+        missing = Operator::FULL_SET - operator_metadata.keys
+        return if missing.empty?
+
+        raise ArgumentError, "Missing operator metadata for: #{missing.join(', ')}"
+      end
+    end
+  end
+end

data/lib/henitai/cli/options.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+require "optparse"
+
+module Henitai
+  class CLI
+    # Builds the OptionParser instances for the `run` and `clean` commands and
+    # parses argv into an options Hash. Help/version options set
+    # +@command_halted+ so the caller can skip the rest of the command.
+    module Options
+      private
+
+      def parse_run_options
+        options = {}
+        build_run_option_parser(options).parse!(@argv)
+        options
+      end
+
+      def parse_clean_options
+        options = {}
+        build_clean_option_parser(options).parse!(@argv)
+        options
+      end
+
+      def build_run_option_parser(options)
+        OptionParser.new do |opts|
+          opts.banner = "Usage: henitai run [options] [SUBJECT_PATTERN...]"
+          add_since_option(opts, options)
+          add_integration_option(opts, options)
+          add_config_option(opts, options)
+          add_operator_option(opts, options)
+          add_jobs_option(opts, options)
+          add_output_option(opts, options)
+          add_survivors_from_option(opts, options)
+          add_fail_on_survivors_option(opts, options)
+          add_help_option(opts)
+          add_version_option(opts)
+        end
+      end
+
+      def build_clean_option_parser(options)
+        OptionParser.new do |opts|
+          opts.banner = "Usage: henitai clean [options]"
+          add_config_option(opts, options)
+          add_help_option(opts)
+          add_version_option(opts)
+        end
+      end
+
+      def add_since_option(opts, options)
+        opts.on("--since GIT_REF", "Only mutate subjects changed since GIT_REF") do |ref|
+          options[:since] = ref
+        end
+      end
+
+      def add_integration_option(opts, options)
+        opts.on("--use INTEGRATION", "Test framework integration (rspec)") do |name|
+          options[:integration] = name
+        end
+      end
+
+      def add_config_option(opts, options)
+        opts.on("--config PATH", "Path to .henitai.yml") do |path|
+          options[:config] = path
+        end
+      end
+
+      def add_operator_option(opts, options)
+        opts.on("--operators SET", "Operator set: light | full") do |set|
+          options[:operators] = set
+        end
+      end
+
+      def add_jobs_option(opts, options)
+        opts.on("--jobs N", Integer, "Number of parallel workers (default: 1)") do |n|
+          options[:jobs] = n
+        end
+      end
+
+      def add_output_option(opts, options)
+        opts.on("--all-logs", "--verbose", "Print all captured child logs") do
+          options[:all_logs] = true
+        end
+      end
+
+      def add_survivors_from_option(opts, options)
+        opts.on(
+          "--survivors-from PATH",
+          "Re-run only survivors from a prior report " \
+          "(partial rerun; threshold checks are skipped; dirty worktrees are included)"
+        ) do |path|
+          options[:survivors_from] = path
+        end
+      end
+
+      def add_fail_on_survivors_option(opts, options)
+        opts.on(
+          "--fail-on-survivors",
+          "Exit 1 for partial reruns when any survivors remain (otherwise exits 0)"
+        ) do
+          options[:fail_on_survivors] = true
+        end
+      end
+
+      def add_help_option(opts)
+        opts.on("-h", "--help", "Show this help") do
+          puts opts
+          @command_halted = true
+        end
+      end
+
+      def add_version_option(opts)
+        opts.on("-v", "--version", "Show version") do
+          puts Henitai::VERSION
+          @command_halted = true
+        end
+      end
+    end
+  end
+end