henitai 0.2.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b2062372801be4391691c6040c2221147a5b14ec346726466d1abe8e916a7670
-  data.tar.gz: b51bd86b3f98751b4cc28bf0e443c56158fe6051f754e2ed954dc74940824f29
+  metadata.gz: cda194514bf677d142e24c97c1589714041d2c88c4d2b33ffaf642e79c7ebe5d
+  data.tar.gz: 8505d5d6add5b850c5accb4904f43351e129b9261699c58051c35faa1a4b3758
 SHA512:
-  metadata.gz: d128d68a96d10a3aeccdd88654cce9ef2ad53d527f196c1a29c1f02416f7d1b045989766872eef92b1832f8a283fdc726fc3b994098b464b22d91897a2993450
-  data.tar.gz: 9b13d2a228c4fd266b49db1d102ca796cd71c534458a341565fd2c1788088bd33f22c1c32bd5c9eeaee4f72d6c3658ea431a78eb5631960299736aea9575b627
+  metadata.gz: b17e21c51f0d4aac03154d8b782d4e361ea8fa792c03a984b9d5b94deccd2411ffb3fe8a7e6fe096b76b33f2bc211a813618c059642b4dec3e54b8fab4d01d8a
+  data.tar.gz: 109527f73b390086f03b5249dd90e97bf57ad3e34551f94d1f80b8f1e5968699e8d6cefe394ebf87bc10465b2a759de737d5f54257807e654a92cd040fa73f59

data/CHANGELOG.md

@@ -7,6 +7,29 @@ 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
@@ -279,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

@@ -43,7 +43,7 @@ Or install globally:
 gem install henitai
 ```
 
-**Requires Ruby 4.0.2+**
+**Requires Ruby 4.0.0+**
 
 ## Quick start
 
@@ -72,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
@@ -139,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
@@ -160,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.

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

data/lib/henitai/cli/run_command.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Henitai
+  class CLI
+    # Implements `henitai run`: option parsing, pipeline execution, survivors
+    # resolution, and exit-status derivation. Mixed into {CLI} so it shares the
+    # instance (and observable +exit+/+warn+ calls).
+    module RunCommand
+      private
+
+      def run_command
+        @command_halted = false
+        options = parse_run_options
+        return if @command_halted
+
+        config = load_config(options)
+        result = run_pipeline(options, config)
+        exit(exit_status_for(result, config, fail_on_survivors: options[:fail_on_survivors]))
+      rescue StandardError => e
+        handle_run_error(e)
+      end
+
+      def run_pipeline(options, config)
+        resolved_survivors_from = resolve_survivors_from(options[:survivors_from])
+        runner = Runner.new(
+          config:,
+          subjects: subjects_from_argv,
+          since: options[:since],
+          survivors_from: resolved_survivors_from
+        )
+        runner.run
+      end
+
+      def subjects_from_argv
+        @argv.empty? ? nil : @argv.map { |expr| Subject.parse(expr) }
+      end
+
+      def resolve_survivors_from(survivors_from)
+        return nil if survivors_from.nil?
+
+        # Fast path: if the path already points into reports/sessions/<session_id>/,
+        # keep it as-is so activation-recipes.json can be found by the runner.
+        report_dir = File.dirname(survivors_from)
+        parent_dir = File.dirname(report_dir)
+        # Heuristic: treat any path under a directory named "sessions" as already
+        # being a snapshot path; this keeps activation-recipes lookup correct.
+        return survivors_from if File.basename(parent_dir) == "sessions"
+
+        session_id = session_id_from_report(survivors_from)
+        return survivors_from if session_id.nil?
+
+        snapshot_path = survivors_snapshot_path(report_dir, session_id)
+        recipe_path = File.join(report_dir, "sessions", session_id, "activation-recipes.json")
+        return snapshot_path if File.exist?(recipe_path) && File.exist?(snapshot_path)
+
+        # If the recipes exist but the snapshot doesn't (e.g. partial cleanup),
+        # fall back to the path the user provided so the error message points
+        # at what they actually passed.
+
+        survivors_from
+      rescue StandardError => e
+        warn_survivors_from_resolution_error(survivors_from, e)
+        survivors_from
+      end
+
+      def survivors_snapshot_path(report_dir, session_id)
+        File.join(report_dir, "sessions", session_id, "mutation-report.json")
+      end
+
+      def session_id_from_report(path)
+        parsed = JSON.parse(File.read(path))
+        parsed["sessionId"]
+      rescue JSON::ParserError, Errno::ENOENT
+        nil
+      end
+
+      def exit_status_for(result, config, fail_on_survivors: false)
+        if result.respond_to?(:partial_rerun?) && result.partial_rerun?
+          warn "henitai: partial rerun - mutation score threshold not evaluated"
+          return result.survived.positive? ? 1 : 0 if fail_on_survivors
+
+          return 0
+        end
+
+        score = result.mutation_score
+        # No valid mutants to evaluate (e.g. an incremental run with no changed
+        # code) cannot fail a threshold — treat it as success.
+        return 0 if score.nil?
+
+        score.to_i >= config.thresholds.fetch(:low, 60) ? 0 : 1
+      end
+
+      def warn_survivors_from_resolution_error(survivors_from, error)
+        warn(
+          "henitai: warning: could not resolve survivors-from " \
+          "#{survivors_from}: #{error.class}: #{error.message}"
+        )
+      end
+    end
+  end
+end