henitai 0.4.0 → 0.5.1

data/lib/henitai/integration/child_runtime_control.rb

@@ -17,10 +17,13 @@ module Henitai
         CoverageRuntimeSuppressors.suppress_coverage!
       end
 
+      # Signalling, not logging: the thread dump itself is emitted by the
+      # child's USR1 handler, so this only asks for it and gives the child a
+      # moment to write before the caller tears the process group down.
       def debug_child_timeout_dump(pid)
-        return unless debug_child?
+        return unless child_debug_log.enabled?
 
-        debug_child_puts("[henitai-debug-child] timeout_signal_sent pid=#{pid}")
+        child_debug_log.timeout_signal_sent(pid)
         Process.kill(:USR1, pid)
         pause(0.2)
       rescue Errno::ESRCH
@@ -28,22 +31,7 @@ module Henitai
       end
 
       def install_debug_timeout_trap
-        Signal.trap("USR1") { debug_child_thread_dump("timeout") }
-      end
-
-      def debug_child_thread_dump(reason)
-        return unless debug_child?
-
-        debug_child_puts("[henitai-debug-child] thread_dump reason=#{reason}")
-        Thread.list.each_with_index do |thread, index|
-          debug_child_puts(
-            "[henitai-debug-child] thread index=#{index} id=#{thread.object_id} " \
-            "status=#{thread.status.inspect}"
-          )
-          Array(thread.backtrace).each do |line|
-            debug_child_puts("[henitai-debug-child]   #{line}")
-          end
-        end
+        Signal.trap("USR1") { child_debug_log.thread_dump("timeout") }
       end
     end
   end

data/lib/henitai/integration/loaded_features.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Henitai
+  module Integration
+    # Answers whether a test file has already been required, by matching it
+    # against `$LOADED_FEATURES`.
+    #
+    # Both sides need normalizing: `$LOADED_FEATURES` holds absolute paths for
+    # required files but callers hand over repository-relative test paths, and
+    # either side may or may not carry the `.rb` suffix. A feature string that
+    # cannot be expanded (invalid encoding, for instance) falls back to its raw
+    # form rather than aborting the whole check — this runs inside a mutant
+    # child whose only job is diagnostics.
+    class LoadedFeatures
+      def include?(file)
+        candidates = candidates_for(file)
+        $LOADED_FEATURES.any? do |feature|
+          candidates.include?(feature) || candidates.include?(normalize(feature))
+        end
+      end
+
+      def map(files) = files.map { |file| [file, include?(file)] }
+
+      private
+
+      def candidates_for(file)
+        expanded = File.expand_path(file)
+        [expanded, "#{expanded}.rb", file, "#{file}.rb"].uniq
+      end
+
+      def normalize(feature)
+        File.expand_path(feature)
+      rescue StandardError
+        feature
+      end
+    end
+  end
+end

data/lib/henitai/integration/mutant_run_support.rb

@@ -47,7 +47,7 @@ module Henitai
         with_subprocess_env do
           suppress_simplecov!
           suppress_coverage!
-          install_debug_timeout_trap if debug_child?
+          install_debug_timeout_trap if child_debug_log.enabled?
           with_non_interactive_stdin do
             run_child_activation_and_tests(mutant:, test_files:, log_paths:)
           end
@@ -63,11 +63,11 @@ module Henitai
       def run_child_activation_and_tests(mutant:, test_files:, log_paths:)
         scenario_log_support.with_coverage_dir(mutant.id) do
           scenario_log_support.capture_child_output(log_paths) do
-            debug_child_mutant_meta(mutant) if debug_child?
-            debug_child_activation_start(mutant.id)
+            child_debug_log.mutant_meta(mutant)
+            child_debug_log.activation_start(mutant.id)
             activation_result = Mutant::Activator.activate!(mutant)
-            debug_child_activation_check if debug_child?
-            debug_child_activation_end(activation_result, test_files:)
+            child_debug_log.activation_check
+            child_debug_log.activation_end(activation_result, test_files:)
             activation_result == :compile_error ? 2 : run_tests(test_files)
           end
         end

data/lib/henitai/integration/rspec_child_runner.rb

@@ -9,19 +9,20 @@ module Henitai
       private
 
       def run_rspec_runner(test_files)
-        debug_child_puts("[henitai-debug-child] build_rspec_runner_start")
+        log = child_debug_log
+        log.write("[henitai-debug-child] build_rspec_runner_start")
         runner = build_rspec_runner
-        debug_child_puts("[henitai-debug-child] build_rspec_runner_return")
-        debug_child_puts("[henitai-debug-child] configure_rspec_runner_start")
+        log.write("[henitai-debug-child] build_rspec_runner_return")
+        log.write("[henitai-debug-child] configure_rspec_runner_start")
         configure_rspec_runner(runner)
-        debug_child_puts("[henitai-debug-child] configure_rspec_runner_return")
+        log.write("[henitai-debug-child] configure_rspec_runner_return")
         load_rspec_spec_files(test_files)
         run_rspec_specs(runner)
       rescue SystemExit => e
-        debug_child_puts("[henitai-debug-child] runner_run_system_exit status=#{e.status.inspect}")
+        log.write("[henitai-debug-child] runner_run_system_exit status=#{e.status.inspect}")
         raise
       ensure
-        debug_child_puts("[henitai-debug-child] runner_run_ensure")
+        child_debug_log.write("[henitai-debug-child] runner_run_ensure")
       end
 
       def build_rspec_runner
@@ -32,28 +33,28 @@ module Henitai
       end
 
       def configure_rspec_runner(runner)
-        debug_child_puts("[henitai-debug-child] trap_interrupt_start")
+        child_debug_log.write("[henitai-debug-child] trap_interrupt_start")
         ::RSpec::Core::Runner.__send__(:trap_interrupt)
-        debug_child_puts("[henitai-debug-child] trap_interrupt_return")
-        debug_child_puts("[henitai-debug-child] runner_configure_start")
+        child_debug_log.write("[henitai-debug-child] trap_interrupt_return")
+        child_debug_log.write("[henitai-debug-child] runner_configure_start")
         runner.send(:configure, $stderr, $stdout)
-        debug_child_puts("[henitai-debug-child] runner_configure_return")
+        child_debug_log.write("[henitai-debug-child] runner_configure_return")
       end
 
       def load_rspec_spec_files(test_files)
-        debug_child_puts("[henitai-debug-child] load_spec_files_start")
+        child_debug_log.write("[henitai-debug-child] load_spec_files_start")
         ::RSpec.configuration.files_to_run = test_files.map do |file|
           File.expand_path(file)
         end
         ::RSpec.configuration.load_spec_files
-        debug_child_example_count("after_load")
-        debug_child_puts("[henitai-debug-child] load_spec_files_return")
+        child_debug_log.example_count("after_load")
+        child_debug_log.write("[henitai-debug-child] load_spec_files_return")
       end
 
       def run_rspec_specs(runner)
-        debug_child_puts("[henitai-debug-child] run_specs_start")
+        child_debug_log.write("[henitai-debug-child] run_specs_start")
         result = runner.send(:run_specs, ::RSpec.world.ordered_example_groups)
-        debug_child_puts("[henitai-debug-child] run_specs_return result=#{result.inspect}")
+        child_debug_log.write("[henitai-debug-child] run_specs_return result=#{result.inspect}")
         result
       end
     end

data/lib/henitai/integration/rspec_process_runner.rb

@@ -32,7 +32,7 @@ module Henitai
           ended_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)
           @mutex.synchronize do
             @live_count -= 1
-            entry = @intervals.rfind { |i| i[:pid] == pid && i[:ended_at].nil? }
+            entry = @intervals.reverse_each.find { |i| i[:pid] == pid && i[:ended_at].nil? }
             entry[:ended_at] = ended_at if entry
           end
         end
@@ -84,8 +84,13 @@ module Henitai
       # Forks a child, sets process group, activates the mutant, runs tests.
       # Returns a ChildHandle with the forked pid and log_paths.
       def spawn_mutant(integration, mutant:, test_files:, log_paths:)
+        # Captured here, in the parent. Reading Process.ppid inside the child
+        # would race the very death the watchdog looks for: a parent dying
+        # between fork and that read leaves the child with ppid 1 as its
+        # baseline, so it would never consider itself orphaned.
+        parent_pid = Process.pid
         pid = Process.fork do
-          Process.setpgid(0, 0)
+          ChildBootstrap.after_fork!(parent_pid:)
           ENV["HENITAI_MUTANT_ID"] = mutant.id
           Process.exit(
             integration.run_in_child(

data/lib/henitai/integration.rb

@@ -3,10 +3,12 @@
 require "fileutils"
 require "stringio"
 require_relative "process_wakeup"
+require_relative "integration/child_bootstrap"
 require_relative "integration/rspec_process_runner"
 require_relative "integration/scenario_log_support"
 require_relative "integration/coverage_suppression"
-require_relative "integration/child_debug_support"
+require_relative "integration/child_debug_log"
+require_relative "integration/loaded_features"
 require_relative "integration/base"
 require_relative "integration/mutant_run_support"
 require_relative "integration/rspec_child_runner"
@@ -111,13 +113,14 @@ module Henitai
       def run_tests(test_files)
         require "rspec/core"
         ::RSpec.__send__(:configuration).fail_if_no_examples = true
-        debug_child_rspec_trace(test_files:, rspec_options: [], rspec_argv: test_files)
-        debug_child_example_count("before_run") # steep:ignore Ruby::NoMethod
-        debug_child_puts("[henitai-debug-child] runner_run_start")
+        log = child_debug_log
+        log.rspec_trace(test_files:, rspec_options: [], rspec_argv: test_files)
+        log.example_count("before_run")
+        log.write("[henitai-debug-child] runner_run_start")
         status = run_rspec_runner(test_files)
-        debug_child_puts("[henitai-debug-child] runner_run_return status=#{status.inspect}")
-        debug_child_example_count("after_run") # steep:ignore Ruby::NoMethod
-        debug_child_rspec_exit(status)
+        log.write("[henitai-debug-child] runner_run_return status=#{status.inspect}")
+        log.example_count("after_run")
+        log.rspec_exit(status)
         return status if status.is_a?(Integer)
 
         status == true ? 0 : 1

data/lib/henitai/mutation_skip_directives.rb

@@ -25,7 +25,13 @@ module Henitai
   # Matching mutants are reported as ignored by {StaticFilter}, not dropped.
   class MutationSkipDirectives
     DIRECTIVE = /\A#\s*henitai:disable(?<kind>-start|-end)?(?<rest>[:\s].*)?\z/
-    VALID_OPERATOR_NAMES = Operator::FULL_SET
+
+    # The whitelist is the operator *registry*, not the configured set: the
+    # widest set names every operator henitai knows. Narrowing it to the
+    # configured set would reject a directive for a registered operator the
+    # current run happens not to enable — hard-set names above all, which is
+    # precisely where the escape hatch is needed (ADR-12).
+    VALID_OPERATOR_NAMES = Operator::HARD_SET
 
     # A parsed directive: +operators+ is nil (all) or a Set of canonical
     # operator names; +reason+ is optional free text shown in reports.

data/lib/henitai/operators/return_value.rb

@@ -65,7 +65,7 @@ module Henitai
         body = method_node.children.last
         return body unless body&.type == :begin
 
-        body.children.rfind { |child| child.is_a?(Parser::AST::Node) }
+        body.children.reverse_each.find { |child| child.is_a?(Parser::AST::Node) }
       end
 
       # rubocop:disable Lint/BooleanSymbol

data/lib/henitai/orphan_watchdog.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+module Henitai
+  # Makes a forked mutant child exit when its parent dies.
+  #
+  # Children `setpgid(0, 0)` into their own process group, and all parent-side
+  # cleanup (timeout kills, graceful drain, signal traps) only runs while the
+  # parent's event loop is alive. If the parent is SIGKILLed, OOM-killed, or
+  # crashes, its children receive no signal at all: they reparent to init and
+  # keep running, each holding a full Ruby and test-framework image. Runs have
+  # been observed leaving a dozen such orphans behind, several gigabytes in
+  # total.
+  #
+  # A child cannot be told to die by a parent that is already gone, so it has
+  # to notice by itself. This is a poll: portable, and cheap enough at a
+  # multi-second interval that it costs nothing next to running a test suite.
+  # PDEATHSIG (Linux) and kqueue NOTE_EXIT (macOS) would be prompter but are
+  # platform-specific; they can be layered on later behind the same interface.
+  class OrphanWatchdog
+    DEFAULT_INTERVAL = 1.5
+    ENV_ENABLED = "HENITAI_CHILD_WATCHDOG"
+    ENV_INTERVAL = "HENITAI_CHILD_WATCHDOG_INTERVAL"
+
+    # Exit code used when the watchdog fires. 2 classifies as :compile_error
+    # (see ScenarioExecutionResult.status_for), which surfaces in reports and
+    # logs. Codes at 3 and above classify as :killed, which would let a
+    # false positive silently inflate the mutation score -- so a visibly wrong
+    # verdict is preferred to an invisibly wrong one. In the true-positive case
+    # the parent is dead and nothing classifies this child at all.
+    ORPHAN_EXIT_CODE = 2
+
+    # Captured at load time, for the same reason as ProcessLiveness::KILL: the
+    # mutant child runs the host project's own suite, and a spec there stubbing
+    # `Process.ppid` would otherwise make this child believe it had been
+    # reparented and exit itself.
+    PPID = Process.method(:ppid)
+
+    # Opt-OUT, deliberately inverted relative to HENITAI_DEBUG_CHILD's opt-in:
+    # a watchdog that defaulted to off would never protect the runs it exists
+    # for. Set HENITAI_CHILD_WATCHDOG=0 to disable.
+    def self.enabled?(env = ENV)
+      env[ENV_ENABLED] != "0"
+    end
+
+    def self.poll_interval(env = ENV)
+      seconds = Float(env[ENV_INTERVAL], exception: false)
+      seconds&.positive? ? seconds : DEFAULT_INTERVAL
+    end
+
+    # Starts the watchdog in a background thread. Call in the child, right
+    # after fork, with the pid captured in the parent beforehand.
+    #
+    # @return [Thread, nil] nil when disabled
+    def self.start(parent_pid:, env: ENV)
+      return nil unless enabled?(env)
+
+      watchdog = new(parent_pid:, interval: poll_interval(env))
+      Thread.new { watchdog.run }
+    end
+
+    # Every collaborator is injectable so the decision logic can be specced
+    # without forking a process or waiting on a real clock.
+    # rubocop:disable Metrics/ParameterLists
+    def initialize(parent_pid:, interval: DEFAULT_INTERVAL, liveness: ProcessLiveness,
+                   ppid: PPID, on_orphan: nil, sleeper: nil)
+      @parent_pid = parent_pid
+      @interval   = interval
+      @liveness   = liveness
+      @ppid       = ppid
+      @on_orphan  = on_orphan || -> { Kernel.exit!(ORPHAN_EXIT_CODE) }
+      @sleeper    = sleeper || ->(seconds) { Kernel.sleep(seconds) }
+    end
+    # rubocop:enable Metrics/ParameterLists
+
+    # Two arms, because neither alone is sufficient. A changed ppid is
+    # definitive -- we have been reparented, and no pid reuse can fake that --
+    # but it stays equal while the parent lingers as a zombie, which the
+    # liveness probe catches.
+    def orphaned?
+      @ppid.call != @parent_pid || !@liveness.alive?(@parent_pid)
+    end
+
+    # Polls until orphaned, then hands over to the orphan handler -- which by
+    # default calls exit! and so never returns. Checks before sleeping, so a
+    # child forked from an already-dead parent dies immediately rather than
+    # after one interval.
+    def run
+      @sleeper.call(@interval) until orphaned?
+
+      @on_orphan.call
+    end
+  end
+end

data/lib/henitai/process_liveness.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Henitai
+  # Answers whether a process id is still running.
+  #
+  # Extracted so the one subtle rule here lives in a single place: EPERM means
+  # the process exists but belongs to someone else, so it counts as *alive*.
+  # Only ESRCH proves it is gone. Getting that backwards would let
+  # OrphanWatchdog kill live children, and would make the reports-directory
+  # lock report a running owner as dead.
+  module ProcessLiveness
+    # Captured at load time, before any test double can replace
+    # `Process.kill`. A `Method` object keeps pointing at the original
+    # definition even after the singleton method is redefined, which is what
+    # makes this immune to stubbing.
+    #
+    # This is not defensiveness for its own sake: a mutant child runs the host
+    # project's own suite, and a spec in that suite stubbing `Process.kill` to
+    # raise ESRCH made this answer "parent is dead" while the parent was very
+    # much alive. OrphanWatchdog then exited the child, which the scheduler
+    # recorded as CompileError. Observed on henitai's own dogfood run.
+    KILL = Process.method(:kill)
+
+    # @param pid [Integer, nil] process id to probe
+    # @param kill [#call] signalling primitive; injected only by specs, which
+    #   cannot reach {KILL} by stubbing and must not be able to
+    # @return [Boolean] false only when the pid provably does not exist
+    def self.alive?(pid, kill: KILL)
+      return false unless pid.is_a?(Integer)
+
+      kill.call(0, pid)
+      true
+    rescue Errno::ESRCH
+      false
+    rescue StandardError
+      # EPERM and anything unexpected: assume alive, the conservative answer
+      # for every caller.
+      true
+    end
+  end
+end

data/lib/henitai/reports_directory_lock.rb

@@ -18,7 +18,17 @@ module Henitai
       File.open(lock_path, File::RDWR | File::CREAT, 0o644) do |file|
         acquire(file)
         write_owner(file)
-        yield
+        # Registered so a forked mutant child can close its inherited copy: the
+        # flock lives on the shared open file description, so a child that
+        # outlives its parent would otherwise keep this lock held. Unregistered
+        # inside the File.open block, keeping the registration's lifetime a
+        # subset of the handle's.
+        InheritedFdRegistry.register(file)
+        begin
+          yield
+        ensure
+          InheritedFdRegistry.unregister(file)
+        end
       end
     end
 
@@ -55,16 +65,7 @@ module Henitai
 
     # True only when the recorded owner pid provably no longer exists. EPERM
     # means the process is alive but owned by someone else — treated as alive.
-    def dead_owner?(pid)
-      return false unless pid.is_a?(Integer)
-
-      Process.kill(0, pid)
-      false
-    rescue Errno::ESRCH
-      true
-    rescue StandardError
-      false
-    end
+    def dead_owner?(pid) = !ProcessLiveness.alive?(pid)
 
     def write_owner(file)
       file.rewind

data/lib/henitai/result.rb

@@ -15,8 +15,28 @@ module Henitai
     SCHEMA_VERSION = "1.0"
     DEFAULT_THRESHOLDS = { high: 80, low: 60 }.freeze
 
+    # Which outcomes count as "the test suite detected this mutant" for the MS
+    # numerator. Duplicated from Configuration rather than read from it: Result
+    # is a domain object and must not depend on configuration loading. The same
+    # arrangement already exists for DEFAULT_THRESHOLDS, and result_spec asserts
+    # the two constants stay equal.
+    DEFAULT_COVERAGE_CRITERIA = {
+      test_result: true,
+      timeout: true,
+      process_abort: true
+    }.freeze
+
+    # Maps each criterion to the mutant status it governs. process_abort has no
+    # producer in lib/ yet -- nothing classifies a mutant as :runtime_error --
+    # so that entry is forward-looking wiring rather than a live code path.
+    CRITERION_STATUSES = {
+      test_result: :killed,
+      timeout: :timeout,
+      process_abort: :runtime_error
+    }.freeze
+
     attr_reader :mutants, :started_at, :finished_at, :thresholds, :survivor_stats,
-                :session_id, :git_sha, :since
+                :session_id, :git_sha, :since, :coverage_criteria
 
     # @param source_provider [#call] maps a file path to its source string.
     #   Injected so the domain object performs no disk IO; the caller (which
@@ -33,7 +53,7 @@ module Henitai
                    partial_rerun: false, survivor_stats: nil,
                    session_id: SecureRandom.uuid, git_sha: nil,
                    source_provider: ->(_file) { "" }, authoritative: true,
-                   since: nil)
+                   since: nil, coverage_criteria: nil)
       @mutants         = mutants
       @started_at      = started_at
       @finished_at     = finished_at
@@ -45,6 +65,7 @@ module Henitai
       @source_provider = source_provider
       @authoritative   = authoritative
       @since           = since
+      @coverage_criteria = DEFAULT_COVERAGE_CRITERIA.merge(coverage_criteria || {})
     end
     # rubocop:enable Metrics/ParameterLists
 
@@ -140,7 +161,13 @@ module Henitai
     private
 
     def detected_in(list)
-      list.count { |m| %i[killed timeout runtime_error].include?(m.status) }
+      list.count { |m| detected_statuses.include?(m.status) }
+    end
+
+    def detected_statuses
+      @detected_statuses ||= CRITERION_STATUSES.filter_map do |criterion, status|
+        status if @coverage_criteria[criterion]
+      end
     end
 
     def mutation_score_for(list)