henitai 0.2.1 → 0.3.1

data/lib/henitai/cli/clean_command.rb

@@ -16,22 +16,28 @@ module Henitai
         return if @command_halted
 
         config = load_config(options)
-        removed_paths = cleanup_report_artifacts(config)
+        removed_paths = ReportsDirectoryLock.new(reports_dir: config.reports_dir).synchronize do
+          cleanup_report_artifacts(config)
+        end
         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
+        removed_dirs = cleanup_dir_paths(config).select { |path| File.directory?(path) }
+        removed_dirs.each { |path| FileUtils.rm_rf(path) }
+        removed_files = cleanup_file_paths(config).select { |path| File.file?(path) }
+        removed_files.each { |path| FileUtils.rm_f(path) }
+        removed_dirs + removed_files
       end
 
-      def report_cleanup_paths(config)
-        REPORT_CLEANUP_PATHS.map do |relative_path|
-          File.join(config.reports_dir, *relative_path)
-        end
+      def cleanup_file_paths(config)
+        REPORT_CLEANUP_PATHS.map { |relative_path| File.join(config.reports_dir, *relative_path) }
+      end
+
+      def cleanup_dir_paths(config)
+        REPORT_CLEANUP_DIRS.map { |relative_path| File.join(config.reports_dir, *relative_path) }
       end
 
       def clean_summary(removed_paths)

data/lib/henitai/cli/command_support.rb

@@ -21,7 +21,8 @@ module Henitai
             all_logs: options[:all_logs],
             mutation: {
               operators: options[:operators],
-              timeout: options[:timeout]
+              timeout: options[:timeout],
+              timeout_multiplier: options[:timeout_multiplier]
             },
             jobs: options[:jobs]
           }

data/lib/henitai/cli/operator_command.rb

@@ -24,7 +24,8 @@ module Henitai
         "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"]
+        "UpdateOperator" => ["Compound assignment", "x += 1 -> x -= 1"],
+        "EqualityIdentityOperator" => ["Identity-method comparisons", "a == b -> a.eql?(b)"]
       }.freeze
 
       private

data/lib/henitai/cli/options.rb

@@ -1,13 +1,17 @@
 # frozen_string_literal: true
 
 require "optparse"
+require_relative "run_options"
 
 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.
+    # Run-only option definitions live in {RunOptions}.
     module Options
+      include RunOptions
+
       private
 
       def parse_run_options
@@ -25,19 +29,28 @@ module Henitai
       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_run_flag_options(opts, options)
           add_help_option(opts)
           add_version_option(opts)
         end
       end
 
+      def add_run_flag_options(opts, options)
+        add_since_option(opts, options)
+        add_integration_option(opts, options)
+        add_config_option(opts, options)
+        add_operator_option(opts, options)
+        add_timeout_multiplier_option(opts, options)
+        add_jobs_option(opts, options)
+        add_output_option(opts, options)
+        add_survivors_from_option(opts, options)
+        add_incremental_option(opts, options)
+        add_force_option(opts, options)
+        add_dry_run_option(opts, options)
+        add_fail_on_survivors_option(opts, options)
+        add_strict_exit_codes_option(opts, options)
+      end
+
       def build_clean_option_parser(options)
         OptionParser.new do |opts|
           opts.banner = "Usage: henitai clean [options]"
@@ -47,61 +60,12 @@ module Henitai
         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

data/lib/henitai/cli/run_command.rb

@@ -17,18 +17,34 @@ module Henitai
 
         config = load_config(options)
         result = run_pipeline(options, config)
-        exit(exit_status_for(result, config, fail_on_survivors: options[:fail_on_survivors]))
+        exit(run_exit_status(result, config, options))
       rescue StandardError => e
         handle_run_error(e)
       end
 
+      def run_exit_status(result, config, options)
+        # A dry run tests nothing, so there is no score to gate on.
+        return 0 if options[:dry_run]
+
+        exit_status_for(
+          result,
+          config,
+          fail_on_survivors: options[:fail_on_survivors],
+          strict_exit_codes: options[:strict_exit_codes]
+        )
+      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
+          survivors_from: resolved_survivors_from,
+          mode: {
+            dry_run: options.fetch(:dry_run, false),
+            incremental: options.fetch(:incremental, false) && !options.fetch(:force, false)
+          }
         )
         runner.run
       end
@@ -76,7 +92,7 @@ module Henitai
         nil
       end
 
-      def exit_status_for(result, config, fail_on_survivors: false)
+      def exit_status_for(result, config, fail_on_survivors: false, strict_exit_codes: 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
@@ -84,6 +100,23 @@ module Henitai
           return 0
         end
 
+        strict_status = strict_exit_codes ? strict_status_for(result) : nil
+        strict_status || threshold_status_for(result, config)
+      end
+
+      # Expanded, opt-in exit codes (precedence: timeout > runtime/compile
+      # error > threshold miss). The timeout code is informational and
+      # independent of coverage_criteria.timeout: a run can pass its threshold
+      # and still exit 3.
+      def strict_status_for(result)
+        statuses = result.mutants.map(&:status)
+        return 3 if statuses.include?(:timeout)
+        return 4 if statuses.include?(:runtime_error) || statuses.include?(:compile_error)
+
+        nil
+      end
+
+      def threshold_status_for(result, config)
         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.

data/lib/henitai/cli/run_options.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+module Henitai
+  class CLI
+    # Option definitions specific to `henitai run`, mixed into {Options} to
+    # keep each module focused: {Options} owns parser construction and the
+    # shared options, this module owns the run-only flags.
+    module RunOptions
+      private
+
+      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_operator_option(opts, options)
+        opts.on("--operators SET", "Operator set: light | full") do |set|
+          options[:operators] = set
+        end
+      end
+
+      def add_timeout_multiplier_option(opts, options)
+        opts.on(
+          "--timeout-multiplier N", Float,
+          "Multiplier applied to the measured per-mutant test baseline " \
+          "when mutation.timeout is unset (default: 3.0)"
+        ) do |n|
+          options[:timeout_multiplier] = n
+        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_dry_run_option(opts, options)
+        opts.on(
+          "--dry-run",
+          "List the post-filter mutant set without executing mutants (always exits 0)"
+        ) do
+          options[:dry_run] = true
+        end
+      end
+
+      def add_incremental_option(opts, options)
+        opts.on(
+          "--incremental",
+          "Reuse still-valid Killed verdicts from the history store instead of re-executing them"
+        ) do
+          options[:incremental] = true
+        end
+      end
+
+      def add_force_option(opts, options)
+        opts.on(
+          "--force",
+          "Bypass verdict reuse and execute every mutant (only meaningful with --incremental)"
+        ) do
+          options[:force] = true
+        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_strict_exit_codes_option(opts, options)
+        opts.on(
+          "--strict-exit-codes",
+          "Expanded exit codes: 0 threshold met, 1 threshold miss, " \
+          "2 framework error, 3 timeouts present, 4 runtime/compile errors present"
+        ) do
+          options[:strict_exit_codes] = true
+        end
+      end
+    end
+  end
+end

data/lib/henitai/cli.rb

@@ -34,12 +34,20 @@ module Henitai
     include OperatorCommand
 
     REPORT_CLEANUP_PATHS = [
-      %w[mutation-logs baseline.log],
-      %w[mutation-logs baseline.stdout.log],
-      %w[mutation-logs baseline.stderr.log],
       %w[coverage .resultset.json],
       %w[coverage .last_run.json],
-      ["henitai_per_test.json"]
+      ["henitai_per_test.json"],
+      [CoverageBootstrapper::DEPENDENCY_MANIFEST_FILE]
+    ].freeze
+
+    # Whole directories of per-mutant scratch artifacts, removed recursively.
+    # `mutation-logs` accumulates one stdout/stderr/combined log trio per
+    # mutant (and baseline) and `mutation-coverage` one dir per mutant, so both
+    # grow to GBs on a large run; deleting the tree is the only way to reclaim
+    # it (rm_f cannot remove a directory).
+    REPORT_CLEANUP_DIRS = [
+      %w[mutation-logs],
+      %w[mutation-coverage]
     ].freeze
 
     def self.start(argv)

data/lib/henitai/composite_progress_reporter.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Henitai
+  # Fans a single #progress callback out to several observers so the execution
+  # engines keep exactly one progress hook. Used to run the terminal reporter
+  # and the checkpoint writer side by side.
+  class CompositeProgressReporter
+    # Assembles the active progress reporters for a run: the terminal reporter
+    # when terminal output is on, and the checkpoint writer when enabled and a
+    # file report (json/html) is configured. Returns a single reporter when only
+    # one is active, the composite when several are, or nil when none are.
+    def self.for(config:, source_provider:, full_run:)
+      active = [terminal_for(config), checkpoint_for(config, source_provider, full_run)].compact
+      return active.first if active.one?
+
+      active.empty? ? nil : new(active)
+    end
+
+    def self.terminal_for(config)
+      Reporter::Terminal.new(config:) if reporter?(config, "terminal")
+    end
+
+    def self.checkpoint_for(config, source_provider, full_run)
+      return unless config.respond_to?(:checkpoint_enabled) && config.checkpoint_enabled
+      return unless reporter?(config, "json") || reporter?(config, "html")
+
+      CheckpointReporter.new(config:, source_provider:, authoritative: full_run)
+    end
+
+    def self.reporter?(config, name)
+      Array(config.reporters).map(&:to_s).include?(name)
+    end
+
+    def initialize(reporters)
+      @reporters = reporters.compact
+    end
+
+    def progress(mutant, scenario_result: nil)
+      @reporters.each { |reporter| reporter.progress(mutant, scenario_result:) }
+    end
+  end
+end

data/lib/henitai/configuration.rb

@@ -10,10 +10,21 @@ module Henitai
   # Configuration is resolved from built-in defaults and the project-root
   # `.henitai.yml` file.
   class Configuration
-    DEFAULT_TIMEOUT   = 10.0
+    DEFAULT_TIMEOUT = 10.0
+    DEFAULT_TIMEOUT_MULTIPLIER = 3.0
     DEFAULT_OPERATORS = :light
     DEFAULT_JOBS      = 1
     DEFAULT_MAX_FLAKY_RETRIES = 3
+    # Cap on captured child stdout/stderr per stream (bytes). A runaway mutant
+    # (e.g. one that puts henitai's own suite into a spewing recursion) can
+    # otherwise write hundreds of MB per child; overflow is discarded.
+    DEFAULT_MAX_LOG_BYTES = 5_000_000
+    # Ceiling for the per-mutant auto-calibrated timeout (seconds). Keeps a
+    # runaway from running for minutes when the calibrated value is large.
+    DEFAULT_MAX_TIMEOUT = 30.0
+    # Incremental report checkpoint cadence for long full runs.
+    DEFAULT_CHECKPOINT_EVERY = 200
+    DEFAULT_CHECKPOINT_INTERVAL = 30.0
     DEFAULT_REPORTS_DIR = "reports"
     DEFAULT_COVERAGE_CRITERIA = {
       test_result: true,
@@ -23,12 +34,20 @@ module Henitai
     DEFAULT_THRESHOLDS = { high: 80, low: 60 }.freeze
     CONFIG_FILE        = ".henitai.yml"
 
-    attr_reader :integration, :includes, :excludes, :operators, :timeout,
-                :ignore_patterns, :sampling, :jobs,
-                :max_flaky_retries, :coverage_criteria, :thresholds,
+    attr_reader :integration, :includes, :excludes, :test_excludes, :operators, :timeout,
+                :timeout_multiplier, :ignore_patterns, :sampling, :jobs,
+                :max_flaky_retries, :max_log_bytes, :max_timeout,
+                :coverage_criteria, :thresholds,
                 :reporters, :reports_dir,
+                :checkpoint_enabled, :checkpoint_every, :checkpoint_interval,
                 :dashboard, :all_logs
 
+    # True when mutation.timeout was set explicitly (file or CLI override);
+    # a fixed timeout disables per-mutant auto-calibration.
+    def timeout_configured?
+      @timeout_configured
+    end
+
     # @param path [String] path to .henitai.yml (default: project root)
     def self.load(path: CONFIG_FILE, overrides: {})
       new(path:, overrides:)
@@ -66,6 +85,7 @@ module Henitai
     def apply_defaults(raw)
       apply_general_defaults(raw)
       apply_mutation_defaults(raw)
+      apply_reports_defaults(raw)
       apply_analysis_defaults(raw)
     end
 
@@ -73,6 +93,7 @@ module Henitai
       @integration = resolve_integration_default(raw[:integration])
       @includes = raw[:includes] || ["lib"]
       @excludes = raw[:excludes] || []
+      @test_excludes = raw[:test_excludes] || []
       @jobs = raw.fetch(:jobs, DEFAULT_JOBS)
       @reporters = raw[:reporters] || ["terminal"]
       @reports_dir = raw[:reports_dir] || DEFAULT_REPORTS_DIR
@@ -84,14 +105,25 @@ module Henitai
       mutation = raw[:mutation] || {}
 
       @operators = (mutation[:operators] || DEFAULT_OPERATORS).to_sym
+      @timeout_configured = !mutation[:timeout].nil?
       @timeout = mutation[:timeout] || DEFAULT_TIMEOUT
+      @timeout_multiplier = mutation[:timeout_multiplier] || DEFAULT_TIMEOUT_MULTIPLIER
       @ignore_patterns = mutation[:ignore_patterns] || []
-      @max_flaky_retries = if mutation.key?(:max_flaky_retries)
-                             mutation[:max_flaky_retries]
-                           else
-                             DEFAULT_MAX_FLAKY_RETRIES
-                           end
       @sampling = mutation[:sampling]
+      apply_mutation_limit_defaults(mutation)
+    end
+
+    def apply_mutation_limit_defaults(mutation)
+      @max_flaky_retries = mutation.fetch(:max_flaky_retries, DEFAULT_MAX_FLAKY_RETRIES)
+      @max_log_bytes = mutation[:max_log_bytes] || DEFAULT_MAX_LOG_BYTES
+      @max_timeout = mutation[:max_timeout] || DEFAULT_MAX_TIMEOUT
+    end
+
+    def apply_reports_defaults(raw)
+      reports = raw[:reports] || {}
+      @checkpoint_enabled = reports.fetch(:checkpoint, true)
+      @checkpoint_every = reports[:checkpoint_every] || DEFAULT_CHECKPOINT_EVERY
+      @checkpoint_interval = reports[:checkpoint_interval] || DEFAULT_CHECKPOINT_INTERVAL
     end
 
     def apply_analysis_defaults(raw)

data/lib/henitai/configuration_validator/rules.rb

@@ -34,6 +34,10 @@ module Henitai
         Scalars.validate_string_array(raw[:excludes], "excludes")
       end
 
+      def validate_test_excludes(raw)
+        Scalars.validate_string_array(raw[:test_excludes], "test_excludes")
+      end
+
       def validate_jobs(raw)
         value = raw[:jobs]
         return if value.nil?
@@ -50,6 +54,17 @@ module Henitai
         Scalars.validate_optional_string(raw[:reports_dir], "reports_dir")
       end
 
+      def validate_reports(raw)
+        value = raw[:reports]
+        return if value.nil?
+
+        ensure_hash!(value, "reports")
+        warn_unknown_keys(value, VALID_REPORTS_KEYS, "reports")
+        Scalars.validate_boolean(value[:checkpoint], "reports.checkpoint") unless value[:checkpoint].nil?
+        Scalars.validate_checkpoint_every(value[:checkpoint_every])
+        Scalars.validate_checkpoint_interval(value[:checkpoint_interval])
+      end
+
       def validate_all_logs(raw)
         value = raw[:all_logs]
         return if value.nil?
@@ -81,7 +96,10 @@ module Henitai
 
       def validate_mutation_limits(value)
         Scalars.validate_timeout(value[:timeout])
+        Scalars.validate_timeout_multiplier(value[:timeout_multiplier])
         Scalars.validate_max_flaky_retries(value[:max_flaky_retries])
+        Scalars.validate_max_log_bytes(value[:max_log_bytes])
+        Scalars.validate_max_timeout(value[:max_timeout])
       end
 
       def validate_mutation_filters(value)

data/lib/henitai/configuration_validator/scalars.rb

@@ -30,6 +30,16 @@ module Henitai
         )
       end
 
+      def validate_timeout_multiplier(value)
+        return if value.nil?
+        return if value.is_a?(Numeric) && value.positive?
+
+        Rules.configuration_error(
+          "Invalid configuration value for mutation.timeout_multiplier: " \
+          "expected positive Numeric, got #{value.inspect}"
+        )
+      end
+
       def validate_threshold(value, path)
         return if value.is_a?(Integer) && value.between?(0, 100)
 
@@ -83,6 +93,42 @@ module Henitai
         )
       end
 
+      def validate_max_log_bytes(value)
+        return if value.nil?
+        return if value.is_a?(Integer) && value.positive?
+
+        Rules.configuration_error(
+          "Invalid configuration value for mutation.max_log_bytes: expected Integer > 0, got #{value.inspect}"
+        )
+      end
+
+      def validate_max_timeout(value)
+        return if value.nil?
+        return if value.is_a?(Numeric) && value.positive?
+
+        Rules.configuration_error(
+          "Invalid configuration value for mutation.max_timeout: expected positive Numeric, got #{value.inspect}"
+        )
+      end
+
+      def validate_checkpoint_every(value)
+        return if value.nil?
+        return if value.is_a?(Integer) && value.positive?
+
+        Rules.configuration_error(
+          "Invalid configuration value for reports.checkpoint_every: expected Integer > 0, got #{value.inspect}"
+        )
+      end
+
+      def validate_checkpoint_interval(value)
+        return if value.nil?
+        return if value.is_a?(Numeric) && value.positive?
+
+        Rules.configuration_error(
+          "Invalid configuration value for reports.checkpoint_interval: expected positive Numeric, got #{value.inspect}"
+        )
+      end
+
       def validate_sampling_ratio(value)
         return if value.nil?
         return if value.is_a?(Numeric) && value >= 0.0 && value <= 1.0

data/lib/henitai/configuration_validator.rb

@@ -13,16 +13,21 @@ module Henitai
       integration
       includes
       excludes
+      test_excludes
       mutation
       coverage_criteria
       thresholds
       reporters
       reports_dir
+      reports
       all_logs
       dashboard
       jobs
     ].freeze
-    VALID_MUTATION_KEYS = %i[operators timeout ignore_patterns max_flaky_retries sampling].freeze
+    VALID_MUTATION_KEYS = %i[
+      operators timeout timeout_multiplier ignore_patterns max_flaky_retries max_log_bytes max_timeout sampling
+    ].freeze
+    VALID_REPORTS_KEYS = %i[checkpoint checkpoint_every checkpoint_interval].freeze
     VALID_SAMPLING_KEYS = %i[ratio strategy].freeze
     VALID_COVERAGE_CRITERIA_KEYS = %i[test_result timeout process_abort].freeze
     VALID_THRESHOLDS_KEYS = %i[high low].freeze
@@ -34,9 +39,11 @@ module Henitai
       validate_integration
       validate_includes
       validate_excludes
+      validate_test_excludes
       validate_jobs
       validate_reporters
       validate_reports_dir
+      validate_reports
       validate_all_logs
       validate_dashboard
       validate_mutation