active_mutator 0.6.1 → 0.7.0

data/lib/active_mutator/events.rb

@@ -0,0 +1,55 @@
+require "monitor"
+
+module ActiveMutator
+  # Internal event bus for run diagnostics. Producers call
+  # `emit(type, **fields)`; listeners get a frozen Event. With no listeners
+  # emit returns at once, so a default run pays nothing. Not a public hook
+  # API: the NDJSON file (--events) is the public contract.
+  class Events
+    # at: wall time; elapsed: monotonic seconds since the bus was built.
+    Event = Data.define(:type, :at, :elapsed, :fields)
+
+    def initialize(clock: -> { Process.clock_gettime(Process::CLOCK_MONOTONIC) }, wall: -> { Time.now })
+      @clock = clock
+      @wall = wall
+      @started = clock.call
+      @listeners = []
+      # The memory sampler emits from its own thread. A Monitor, not a Mutex:
+      # the sampler also emits from inside its own listener call (a sample
+      # at each phase boundary), which re-enters on the same thread.
+      @lock = Monitor.new
+    end
+
+    # A listener is anything with #call(event), or a block.
+    def subscribe(listener = nil, &block)
+      @listeners << (listener || block)
+      self
+    end
+
+    # Not an endless def: its one line runs at load, so coverage can't tie
+    # it to the specs that call it.
+    def listening?
+      !@listeners.empty?
+    end
+
+    # Emits phase_start, runs the block, emits phase_end, and returns the
+    # block's value. A phase that raises gets no phase_end, so the last
+    # unmatched phase_start marks where a run died.
+    def phase(name, **fields)
+      emit(:phase_start, phase: name, **fields)
+      result = yield
+      emit(:phase_end, phase: name)
+      result
+    end
+
+    def emit(type, **fields)
+      return if @listeners.empty?
+
+      @lock.synchronize do
+        event = Event.new(type: type, at: @wall.call, elapsed: @clock.call - @started, fields: fields.freeze)
+        @listeners.each { |listener| listener.call(event) }
+      end
+      nil
+    end
+  end
+end

data/lib/active_mutator/memory_ceiling.rb

@@ -0,0 +1,59 @@
+module ActiveMutator
+  # --max-rss: a ceiling on the gem's total memory (the parent, its workers,
+  # and the baseline child), read from the sampler's `memory` events. Warns
+  # once at 90%. At 100% it trips the abort flag, and whoever owns the
+  # running processes kills them, so the run ends with exit 3 and a partial
+  # score instead of an OOM kill that leaves nothing.
+  class MemoryCeiling
+    SIZE = /\A(\d+(?:\.\d+)?)([gm]?)\z/i
+    WARN_AT = 0.9
+    # Parsing coverage.json peaked at about 5x the file's size (7x with the
+    # CoverageMap built from it). JSON.parse holds Ruby's global lock, so
+    # no sample or signal gets through until it returns: the size is checked
+    # before the parse instead.
+    PARSE_COST = 5
+
+    # "6G", "6144M", or plain MB ("6144") to kB; nil for anything else.
+    def self.parse_kb(text)
+      match = SIZE.match(text.to_s.strip)
+      return unless match
+
+      mb = Float(match[1]) * (match[2].casecmp?("g") ? 1024 : 1)
+      kb = (mb * 1024).round
+      kb if kb.positive?
+    end
+
+    def initialize(max_rss_kb:, events:, abort:)
+      @max_rss_kb = max_rss_kb
+      @events = events
+      @abort = abort
+    end
+
+    # Events listener. Runs on whichever thread emitted the sample.
+    def call(event)
+      fields = event.fields
+      if event.type == :memory
+        @last_total_kb = fields[:total_pss_kb] || @last_total_kb
+        check(fields[:total_pss_kb])
+      elsif event.type == :phase_start && fields[:phase] == :coverage_load
+        check(@last_total_kb.to_i + (fields[:bytes] / 1024 * PARSE_COST), coverage_bytes: fields[:bytes])
+      end
+    end
+
+    private
+
+    # Quiet once the run is stopping: samples keep coming until it exits.
+    def check(total_kb, **extra)
+      return if total_kb.nil? || @abort.tripped?
+
+      fields = { total_pss_kb: total_kb, max_rss_kb: @max_rss_kb, **extra }
+      if total_kb >= @max_rss_kb
+        @events.emit(:memory_ceiling, **fields)
+        @abort.trip!(:memory_ceiling)
+      elsif !@warned && total_kb >= @max_rss_kb * WARN_AT
+        @warned = true
+        @events.emit(:memory_warning, **fields)
+      end
+    end
+  end
+end

data/lib/active_mutator/memory_probe.rb

@@ -0,0 +1,82 @@
+module ActiveMutator
+  # Reads process and system memory for run diagnostics and --max-rss.
+  #
+  #   Linux: /proc/<pid>/status (VmRSS, VmHWM) and smaps_rollup (Pss), plus
+  #          meminfo, pressure/memory, and loadavg for the system fields.
+  #   macOS: one `ps -o pid=,rss=` per call for every pid; no peak, Pss, or
+  #          system fields.
+  #   other: nothing; diagnostics still print, memory fields blank.
+  #
+  # `proc_root`, `platform`, and `ps` are injectable so specs read fixtures.
+  class MemoryProbe
+    DEFAULT_PS = lambda do |pids|
+      IO.popen(["ps", "-o", "pid=,rss=", "-p", pids.join(",")], err: File::NULL, &:read)
+    end
+
+    # This process's peak RSS in KB (VmHWM). A worker can exit between two
+    # memory samples, so it reports its own peak. nil off Linux.
+    def self.peak_rss_kb(proc_root: "/proc")
+      status_kb(File.join(proc_root, "self", "status"), "VmHWM")
+    end
+
+    def self.status_kb(path, key)
+      line = File.foreach(path).find { |l| l.start_with?("#{key}:") }
+      line && line[/\d+/].to_i
+    rescue SystemCallError
+      nil
+    end
+
+    def initialize(proc_root: "/proc", platform: RUBY_PLATFORM, ps: DEFAULT_PS)
+      @proc_root = proc_root
+      @ps = ps
+      @mode = if File.directory?(proc_root) then :linux
+              elsif platform.include?("darwin") then :ps
+              end
+    end
+
+    # {pid => {rss_kb:, hwm_kb:, pss_kb:}}; pids that are gone are left out.
+    def processes(pids)
+      case @mode
+      when :linux then pids.filter_map { |pid| linux_process(pid) }.to_h
+      when :ps then pids.empty? ? {} : ps_processes(pids)
+      else {}
+      end
+    end
+
+    # Linux only; nil elsewhere. Each field is nil when its file is missing.
+    def system
+      return unless @mode == :linux
+
+      meminfo = File.join(@proc_root, "meminfo")
+      { mem_available_kb: self.class.status_kb(meminfo, "MemAvailable"),
+        swap_total_kb: self.class.status_kb(meminfo, "SwapTotal"),
+        swap_free_kb: self.class.status_kb(meminfo, "SwapFree"),
+        psi_some_avg10: read(File.join("pressure", "memory"))&.[](/^some avg10=([\d.]+)/, 1)&.to_f,
+        load1: read("loadavg")&.split&.first&.to_f }
+    end
+
+    private
+
+    def linux_process(pid)
+      status = File.join(@proc_root, pid.to_s, "status")
+      rss = self.class.status_kb(status, "VmRSS")
+      return unless rss
+
+      [pid, { rss_kb: rss, hwm_kb: self.class.status_kb(status, "VmHWM"),
+              pss_kb: self.class.status_kb(File.join(@proc_root, pid.to_s, "smaps_rollup"), "Pss") }]
+    end
+
+    def ps_processes(pids)
+      @ps.call(pids).lines.to_h do |line|
+        pid, rss = line.split.map(&:to_i)
+        [pid, { rss_kb: rss, hwm_kb: nil, pss_kb: nil }]
+      end
+    end
+
+    def read(rel)
+      File.read(File.join(@proc_root, rel))
+    rescue SystemCallError
+      nil
+    end
+  end
+end

data/lib/active_mutator/reporter/github.rb

@@ -12,13 +12,24 @@ module ActiveMutator
 
       def on_result(result) = @terminal.on_result(result)
 
-      def summary(results, invalid_count:, empty_plan: false)
-        @terminal.summary(results, invalid_count: invalid_count, empty_plan: empty_plan)
+      def summary(results, invalid_count:, empty_plan: false, aborted: nil)
+        @terminal.summary(results, invalid_count: invalid_count, empty_plan: empty_plan, aborted: aborted)
         results.select { |r| r.status == :survived }.each { |r| annotate(r) }
+        annotate_abort(aborted, results) if aborted
       end
 
       private
 
+      # One annotation for the whole run, after the survivors that did finish.
+      def annotate_abort(aborted, results)
+        reason = Terminal::ABORT_LABELS.fetch(aborted[:reason])
+        lines = ["The run stopped early (#{reason}), so this is not a full result."]
+        in_flight = aborted[:in_flight].map { |entry| Terminal.in_flight_label(entry) }
+        lines << "In flight: #{in_flight.join("; ")}" unless in_flight.empty?
+        lines << "Partial mutation score: #{Terminal.partial_score(results, aborted[:planned])}"
+        @out.puts "::error title=Mutation run aborted::#{encode(lines.join("\n"))}"
+      end
+
       def annotate(result)
         m = result.mutation
         file = m.subject.file.delete_prefix(@root.chomp("/") + "/")

data/lib/active_mutator/reporter/json.rb

@@ -11,21 +11,33 @@ module ActiveMutator
 
       # An empty plan has no score (null) and its own exit_reason, so a CI
       # consumer can tell "nothing to mutate" from "everything was killed" (#45).
-      def summary(results, invalid_count:, empty_plan: false)
+      # An aborted run has `complete: false`, and its score covers only the
+      # mutants that finished (null if none did).
+      def summary(results, invalid_count:, empty_plan: false, aborted: nil)
         counts = Terminal.counts(results)
         @out.puts JSON.pretty_generate(
-          "score" => empty_plan ? nil : Terminal.score(counts),
+          "complete" => aborted.nil?,
+          "score" => score(results, counts, empty_plan, aborted),
           "counts" => counts.transform_keys(&:to_s),
           "invalid" => invalid_count,
           "operators" => OperatorStats.call(results),
           "results" => results.map { |r| serialize(r) },
-          "exit_reason" => exit_reason(counts, empty_plan)
+          "in_flight" => aborted ? aborted[:in_flight] : [],
+          "planned" => aborted ? aborted[:planned] : results.size,
+          "exit_reason" => exit_reason(counts, empty_plan, aborted)
         )
       end
 
       private
 
-      def exit_reason(counts, empty_plan)
+      def score(results, counts, empty_plan, aborted)
+        return nil if empty_plan || (aborted && results.empty?)
+
+        Terminal.score(counts)
+      end
+
+      def exit_reason(counts, empty_plan, aborted)
+        return aborted[:reason] == :memory_ceiling ? "memory_ceiling" : "interrupted" if aborted
         return "empty_plan" if empty_plan
         return "unaccepted_survivors" if counts[:survived].positive?
         return "worker_errors" if counts[:error].positive?
@@ -43,7 +55,9 @@ module ActiveMutator
           "line" => m.line,
           "original" => m.original_snippet,
           "replacement" => m.edit.replacement,
-          "details" => result.details
+          "details" => result.details,
+          "seconds" => result.seconds,
+          "peak_rss_kb" => result.peak_rss_kb
         }
       end
     end

data/lib/active_mutator/reporter/stryker_json.rb

@@ -34,13 +34,19 @@ module ActiveMutator
 
       # A zero-mutant report is valid schema output, so an empty plan writes the
       # same file with no files/mutants; the flag is accepted for contract parity.
-      def summary(results, invalid_count:, empty_plan: false)
+      # An aborted run reports the finished mutants only: the schema has no
+      # "didn't finish" status that wouldn't skew the score.
+      def summary(results, invalid_count:, empty_plan: false, aborted: nil)
         report = build_report(results, invalid_count)
         path = File.join(@root, REPORT_PATH)
         # An empty plan skips the baseline, which used to create this dir.
         FileUtils.mkdir_p(File.dirname(path))
         AtomicFile.write(path, JSON.pretty_generate(report))
         @out.puts "", "", "Stryker report written to #{REPORT_PATH}"
+        return unless aborted
+
+        @out.puts "Run aborted (#{Terminal::ABORT_LABELS.fetch(aborted[:reason])}): " \
+                  "the report covers only the #{results.size} mutants that finished"
       end
 
       private

data/lib/active_mutator/reporter/terminal.rb

@@ -3,6 +3,7 @@ module ActiveMutator
     class Terminal
       CHARS = { killed: ".", survived: "S", timeout: "T", error: "E", uncovered: "U", accepted: "A",
                 skipped: "-" }.freeze
+      ABORT_LABELS = { sigint: "SIGINT", sigterm: "SIGTERM", memory_ceiling: "memory ceiling" }.freeze
 
       def initialize(out: $stdout)
         @out = out
@@ -21,12 +22,18 @@ module ActiveMutator
 
       # `empty_plan: true` means a --since/--subject scope planned nothing: the
       # count block still prints, but there is no score to report (#45).
-      def summary(results, invalid_count:, empty_plan: false)
+      # `aborted: {reason:, in_flight:, planned:}` means the run stopped early
+      # and `results` holds only the mutants that finished.
+      def summary(results, invalid_count:, empty_plan: false, aborted: nil)
         counts = self.class.counts(results)
         @out.puts "", ""
         counts.each { |status, count| @out.puts "#{status}: #{count}" }
         @out.puts "invalid (discarded): #{invalid_count}"
-        @out.puts format("Mutation score: %.1f%%", score(counts) * 100) unless empty_plan
+        if aborted
+          print_aborted(aborted, results)
+        elsif !empty_plan
+          @out.puts format("Mutation score: %.1f%%", score(counts) * 100)
+        end
         print_group("Surviving mutants:", results.select { |r| r.status == :survived })
         print_group("Errored mutants (not detected):", results.select { |r| r.status == :error })
         print_group("Timed-out mutants (counted as detected):", results.select { |r| r.status == :timeout })
@@ -48,10 +55,32 @@ module ActiveMutator
         detected.to_f / denominator
       end
 
+      # "71.3% (412 of 764 mutants)": the score over the finished mutants,
+      # and how many finished out of the plan (unknown if planning never ended).
+      def self.partial_score(results, planned)
+        score = results.empty? ? "n/a" : format("%.1f%%", score(counts(results)) * 100)
+        "#{score} (#{results.size}#{" of #{planned}" if planned} mutants)"
+      end
+
+      def self.in_flight_label(entry)
+        "##{entry[:seq]} #{entry[:subject]} (#{entry[:file]}:#{entry[:line]}) #{entry[:description]}"
+      end
+
       private
 
       def score(counts) = self.class.score(counts)
 
+      # Never labeled "Mutation score:", so nothing scraping the log can take
+      # a partial run for a finished one.
+      def print_aborted(aborted, results)
+        @out.puts "", "Run aborted (#{ABORT_LABELS.fetch(aborted[:reason])}): partial results"
+        unless aborted[:in_flight].empty?
+          @out.puts "In flight (stopped before a verdict):"
+          aborted[:in_flight].each { |entry| @out.puts "  #{self.class.in_flight_label(entry)}" }
+        end
+        @out.puts "Partial mutation score: #{self.class.partial_score(results, aborted[:planned])}"
+      end
+
       def print_operator_stats(stats)
         @out.puts "", "Equivalent-rate by operator (survived / (killed + survived)):"
         stats.sort_by { |_, s| -s["equivalent_rate"] }.each do |operator, s|

data/lib/active_mutator/result.rb

@@ -1,6 +1,12 @@
 module ActiveMutator
   # status: :killed | :survived | :timeout | :error | :uncovered | :accepted | :skipped
-  Result = Data.define(:mutation, :status, :details) do
+  # seconds: worker wall time; peak_rss_kb: the worker's own peak RSS (nil
+  # off Linux). Both nil for results that never ran in a worker.
+  Result = Data.define(:mutation, :status, :details, :seconds, :peak_rss_kb) do
+    def initialize(mutation:, status:, details:, seconds: nil, peak_rss_kb: nil)
+      super
+    end
+
     def detected? = %i[killed timeout].include?(status)
   end
 end