active_mutator 0.6.0 → 0.7.0

data/lib/active_mutator/runner.rb

@@ -5,62 +5,35 @@ module ActiveMutator
     # What discovery saw, beyond the final subject list. `scanned_files` are
     # root-relative source files after path expansion and excludes, minus
     # spec_paths; `since_candidates` are the --since diff's files among them;
-    # `since_matched_all` are the since-covered subjects before --no-class-level
-    # drops class bodies. The last two feed the --allow-empty verdict (#46).
-    Discovery = Data.define(:subjects, :scanned_files, :since_candidates, :since_matched_all)
+    # `since_matched_all` are the since-covered subjects before --subject and
+    # --no-class-level narrow them; `since_filter` is the --since SinceFilter (nil
+    # without --since). The last three feed the --allow-empty verdict (#46).
+    Discovery = Data.define(:subjects, :scanned_files, :since_candidates, :since_matched_all, :since_filter)
 
-    def initialize(config, reporter: nil)
+    SIGNALS = { "INT" => :sigint, "TERM" => :sigterm }.freeze
+    # An aborted run never passes, whatever --fail-at says.
+    EXIT_CODES = { sigint: 130, sigterm: 143, memory_ceiling: 3 }.freeze
+
+    def initialize(config, reporter: nil, events: nil)
       @config = config
       @reporter = reporter || build_reporter
+      @events = events || build_events
+      @abort = AbortFlag.new
     end
 
+    # The traps go in first so boot, planning, and the baseline are covered
+    # too, and come out last so the host gets its own handlers back.
     def call
-      ENV["ACTIVE_MUTATOR"] = "1"
-      load_operators
-      ClosureReload.cap = @config.class_level_closure_cap
-      preload!
-      preload_spec_helper!
-      discovery = discover
-      subjects = discovery.subjects
-      analyses = subjects.map { |s| Engine.new.analyze(s) }
-      mutations = analyses.flat_map(&:mutations)
-      mutations = mutations.first(@config.max_mutants) if @config.max_mutants
-      invalid_count = analyses.sum(&:invalid_count)
-      # Decide emptiness before the baseline: a scoped run that plans nothing
-      # has no use for a coverage map, and building one spawns the whole spec
-      # suite (#47).
-      if mutations.empty? && (@config.since || @config.subject_filter)
-        return debug_plan([], []) if @config.debug_plan
-
-        return empty_plan_exit(invalid_count, discovery)
-      end
-
-      map = Baseline.new(root: @config.root, spec_paths: @config.spec_paths)
-              .coverage_map(force: @config.force_baseline)
-      @reporter.coverage_map = map if @reporter.respond_to?(:coverage_map=)
-
-      fingerprints = Fingerprint.for_mutations(mutations, root: @config.root)
-      ledger = AcceptedLedger.load(@config.root)
-      scanned_files = prune_scope(subjects)
-      warn_stale(ledger, fingerprints.values, scanned_files)
-
-      items, pre_results, phase1_ids = plan_work(mutations, map, ledger: ledger, fingerprints: fingerprints)
-      return debug_plan(items, pre_results) if @config.debug_plan
-
-      pre_results.each { |r| @reporter.on_result(r) }
-      calibrators = if @config.adaptive_timeout
-                      { parallel: TimeoutCalibrator.new, serial: TimeoutCalibrator.new }
-                    end
-      scheduler = Scheduler.new(jobs: @config.jobs, on_result: @reporter.method(:on_result),
-                                calibrators: calibrators)
-      results = scheduler.run(items) + pre_results
-      # Phase 2 runs on its own scheduler (built lazily inside), so pass nil.
-      results = escalate_class_body_survivors(results, nil, map, phase1_ids: phase1_ids)
-
-      accept_survivors!(ledger, results, fingerprints, scanned_files) if @config.accept_survivors
-
-      @reporter.summary(results, invalid_count: invalid_count)
-      exit_code(results)
+      previous_traps = trap_signals
+      events_file = open_events_file
+      sampler = start_sampler
+      run
+    rescue Aborted => e
+      aborted_exit(e)
+    ensure
+      sampler&.stop
+      events_file&.close
+      restore_traps(previous_traps)
     end
 
     # Returns [work_items, pre_results, phase1_ids]. phase1_ids maps each
@@ -121,8 +94,16 @@ module ActiveMutator
       end
       return results if items.empty?
 
-      scheduler ||= Scheduler.new(jobs: @config.jobs)
-      escalated = scheduler.run(items.values).to_h { |res| [res.mutation, res] }
+      # Numbered after phase 1's mutants, so seq stays unique across the run.
+      scheduler ||= Scheduler.new(jobs: @config.jobs, events: @events, first_seq: phase1_ids.size + 1, abort: @abort)
+      escalated = begin
+        @events.phase(:escalating, mutants: items.size) do
+          scheduler.run(items.values).to_h { |res| [res.mutation, res] }
+        end
+      rescue Aborted => e
+        # Every phase-1 verdict is final; a half-done escalation proves nothing.
+        raise e.with_results(results)
+      end
       results.map do |r|
         # A replacement only ever exists for a survived candidate (items is
         # built solely from those), so no redundant status re-check is needed.
@@ -157,12 +138,116 @@ module ActiveMutator
 
     private
 
+    def run
+      @events.phase(:boot) { boot! }
+      discovery, analyses = @events.phase(:planning) do
+        found = discover
+        [found, found.subjects.map { |s| Engine.new.analyze(s) }]
+      end
+      subjects = discovery.subjects
+      mutations = analyses.flat_map(&:mutations)
+      mutations = mutations.first(@config.max_mutants) if @config.max_mutants
+      @planned = mutations.size
+      @invalid_count = analyses.sum(&:invalid_count)
+      # Decide emptiness before the baseline: a scoped run that plans nothing
+      # has no use for a coverage map, and building one spawns the whole spec
+      # suite (#47).
+      if mutations.empty? && (@config.since || @config.subject_filter)
+        return debug_plan([], []) if @config.debug_plan
+
+        return empty_plan_exit(@invalid_count, discovery)
+      end
+
+      map = Baseline.new(root: @config.root, spec_paths: @config.spec_paths, events: @events, abort: @abort)
+              .coverage_map(force: @config.force_baseline)
+      @reporter.coverage_map = map if @reporter.respond_to?(:coverage_map=)
+
+      fingerprints = Fingerprint.for_mutations(mutations, root: @config.root)
+      ledger = AcceptedLedger.load(@config.root)
+      scanned_files = prune_scope(subjects)
+      warn_stale(ledger, fingerprints.values, scanned_files)
+
+      items, pre_results, phase1_ids = plan_work(mutations, map, ledger: ledger, fingerprints: fingerprints)
+      return debug_plan(items, pre_results) if @config.debug_plan
+
+      # From here on a trip only records its reason. Raised at once, it could
+      # land between two steps (the sample as mutating ends, the spec reads
+      # before escalation) and drop every finished verdict. Each step checks
+      # the flag instead and raises with the results it has.
+      results = @abort.deferred do
+        done = @events.phase(:mutating, mutants: items.size) { mutate(items, pre_results) }
+        stop_if_tripped!(done)
+        # Phase 2 runs on its own scheduler (built lazily inside), so pass nil.
+        done = escalate_class_body_survivors(done, nil, map, phase1_ids: phase1_ids)
+        stop_if_tripped!(done)
+
+        reporting(done) do
+          accept_survivors!(ledger, done, fingerprints, scanned_files) if @config.accept_survivors
+          @reporter.summary(done, invalid_count: @invalid_count)
+        end
+        done
+      end
+      exit_code(results)
+    end
+
+    def mutate(items, pre_results)
+      pre_results.each { |r| @reporter.on_result(r) }
+      calibrators = if @config.adaptive_timeout
+                      { parallel: TimeoutCalibrator.new, serial: TimeoutCalibrator.new }
+                    end
+      scheduler = Scheduler.new(jobs: @config.jobs, on_result: @reporter.method(:on_result),
+                                calibrators: calibrators, events: @events, abort: @abort)
+      scheduler.run(items) + pre_results
+    rescue Aborted => e
+      raise e.with_results(e.results + pre_results)
+    end
+
+    # The trap only trips the flag: no I/O is safe inside a handler. The
+    # main loop does the killing and raises Aborted.
+    def trap_signals
+      SIGNALS.to_h { |sig, reason| [sig, trap(sig) { @abort.trip!(reason) }] }
+    end
+
+    # Passed back as is: a nil handler means the host ignored the signal.
+    def restore_traps(previous)
+      previous.each { |sig, handler| trap(sig, handler) }
+    end
+
+    # No --accept-survivors here: a partial run must not rewrite the ledger.
+    # Once the report starts, a signal only records its reason: the report
+    # finishes, and `--format json` stays one document. The run still exits
+    # as aborted, so a memory breach or a CI cancel never passes.
+    def reporting(results = [], &)
+      @abort.deferred do
+        @reported = true
+        @events.phase(:reporting, &)
+      end
+      stop_if_tripped!(results)
+    end
+
+    def stop_if_tripped!(results)
+      raise Aborted.new(@abort.reason, results: results) if @abort.tripped?
+    end
+
+    # No summary if the full one already went out: a signal landing after
+    # the report would otherwise print a second one.
+    def aborted_exit(error)
+      counts = Reporter::Terminal.counts(error.results)
+      @events.emit(:abort, reason: error.reason, in_flight: error.in_flight, planned: @planned,
+                           counts: counts, score: error.results.empty? ? nil : Reporter::Terminal.score(counts))
+      unless @reported
+        @reporter.summary(error.results, invalid_count: @invalid_count || 0,
+                                         aborted: { reason: error.reason, in_flight: error.in_flight, planned: @planned })
+      end
+      EXIT_CODES.fetch(error.reason)
+    end
+
     # A scoped run that plans nothing must not report "100%" and pass --fail-at:
     # the usual cause is a --since range or --subject filter that matched no
     # mutable code, or class-body code dropped by --no-class-level (#23 covers
     # the zero-subject case for explicit paths).
     def empty_plan_exit(invalid_count, discovery)
-      @reporter.summary([], invalid_count: invalid_count, empty_plan: true)
+      reporting { @reporter.summary([], invalid_count: invalid_count, empty_plan: true) }
       causes = []
       causes << "--since #{@config.since} matched no mutable code" if @config.since
       causes << "--subject #{@config.subject_filter} matched no subjects" if @config.subject_filter
@@ -177,15 +262,31 @@ module ActiveMutator
     end
 
     # --allow-empty forgives an empty plan only when the --since diff touched no
-    # candidate source file (docs-only, spec-only, excluded paths). A changed
-    # candidate that planned nothing is the case worth failing on, unless the
-    # only code it touched is class-body code that --no-class-level dropped.
-    # --subject alone has no diff to judge, so it stays an unconditional 0.
+    # candidate source file (docs-only, spec-only, excluded paths), changed
+    # only comments in them, or deleted code no subject spans (a removed
+    # method). A candidate whose code changed but planned
+    # nothing is the case worth failing on, unless the only code it touched
+    # is class-body code that --no-class-level dropped. --subject alone has no
+    # diff to judge, so it stays an unconditional 0.
     def allow_empty_exit(discovery)
       return 0 unless @config.since
 
-      candidates = discovery.since_candidates
-      return 0 if candidates.empty?
+      filter = discovery.since_filter
+      matched_files = discovery.since_matched_all.map { |s| relative(s.file) }
+      # A deletion no subject spans leaves nothing to mutate. One inside a
+      # subject that still planned nothing falls through to the checks below.
+      deleted = discovery.since_candidates.select do |file|
+        filter.deletion_only?(file) && !matched_files.include?(file) &&
+          Prism.parse_file(File.join(@config.root, file)).success?
+      end
+      # Checked only here, on the empty-plan path: it runs `git show` per file.
+      commented = (discovery.since_candidates - deleted).select { |f| filter.comment_only?(f) }
+      candidates = discovery.since_candidates - deleted - commented
+      if candidates.empty?
+        warn "active_mutator: forgiving empty plan: deletions in #{deleted.join(", ")} left no method to mutate" if deleted.any?
+        warn "active_mutator: forgiving empty plan: only comments changed in #{commented.join(", ")}" if commented.any?
+        return 0
+      end
 
       if !@config.class_level && class_body_only?(discovery.since_matched_all, candidates)
         warn "active_mutator: forgiving empty plan: changed lines are class-body code and --no-class-level is set"
@@ -239,6 +340,14 @@ module ActiveMutator
       end.flatten.uniq.sort
     end
 
+    def boot!
+      ENV["ACTIVE_MUTATOR"] = "1"
+      load_operators
+      ClosureReload.cap = @config.class_level_closure_cap
+      preload!
+      preload_spec_helper!
+    end
+
     # Custom operators must exist in the PARENT before Engine analysis:
     # subclassing Operators::Base self-registers, and forks inherit the
     # loaded class. `requires` can't serve — those load inside the fork's
@@ -278,6 +387,41 @@ module ActiveMutator
       @config.spec_paths.map { |sp| "#{sp}/#{rest}_spec.rb" }
     end
 
+    # Only when something reads the samples. Subscribed last, so each phase
+    # line prints before the sample taken at it.
+    def start_sampler
+      watch_memory if @config.max_rss
+      return unless @events.listening?
+
+      sampler = Sampler.new(events: @events, interval: @config.sample_interval)
+      @events.subscribe(sampler)
+      sampler.start
+    end
+
+    # Without --diagnostics, the 90% warning and the breach still reach stderr.
+    def watch_memory
+      notices = %i[memory_warning memory_ceiling]
+      @events.subscribe(Diagnostics::Text.new(root: @config.root, only: notices)) unless @config.diagnostics
+      @events.subscribe(MemoryCeiling.new(max_rss_kb: @config.max_rss, events: @events, abort: @abort))
+    end
+
+    # Opened per call, not per Runner, so the file is closed on every exit.
+    def open_events_file
+      return unless @config.events_file
+
+      file = File.open(File.expand_path(@config.events_file, @config.root), "w")
+      @events.subscribe(Diagnostics::Ndjson.new(file))
+      file
+    rescue SystemCallError => e
+      raise Error, "cannot write --events file: #{e.message}"
+    end
+
+    def build_events
+      events = Events.new
+      events.subscribe(Diagnostics::Text.new(root: @config.root)) if @config.diagnostics
+      events
+    end
+
     def build_reporter
       case @config.format
       when :json then Reporter::Json.new
@@ -308,21 +452,21 @@ module ActiveMutator
         .sort
       scanned_files = files.map { |f| relative(f) }.reject { |rel| under_spec_paths?(rel) }
       subjects = files.flat_map { |file| SubjectFinder.call(file) }
-      if @config.subject_filter
-        matcher = SubjectMatcher.new(@config.subject_filter)
-        subjects = subjects.select { |s| matcher.match?(s.name) }
-      end
       since_candidates = []
       if @config.since
         filter = SinceFilter.new(ref: @config.since, root: @config.root)
         subjects = subjects.select { |s| filter.cover?(s) }
         since_candidates = filter.changed_files & scanned_files
       end
-      # Class bodies drop out LAST so since_matched_all still knows about them.
       since_matched_all = subjects
+      if @config.subject_filter
+        matcher = SubjectMatcher.new(@config.subject_filter)
+        subjects = subjects.select { |s| matcher.match?(s.name) }
+      end
       subjects = subjects.reject(&:class_body?) unless @config.class_level
       Discovery.new(subjects: subjects, scanned_files: scanned_files,
-                    since_candidates: since_candidates, since_matched_all: since_matched_all)
+                    since_candidates: since_candidates, since_matched_all: since_matched_all,
+                    since_filter: filter)
     end
 
     def relative(file) = file.delete_prefix(@config.root.chomp("/") + "/")

data/lib/active_mutator/sampler.rb

@@ -0,0 +1,69 @@
+module ActiveMutator
+  # Samples the gem's own memory: the parent, every live worker, and the
+  # baseline child. Either side alone tells half the story (0.6.0 died in
+  # the parent, right after the child). It learns worker and child pids from
+  # the event stream, samples at every phase boundary, and, once started,
+  # every `interval` seconds on its own thread. That thread only reads files
+  # and emits, so forks from the main thread stay safe: a fork copies only
+  # the calling thread.
+  class Sampler
+    def initialize(events:, interval:, probe: MemoryProbe.new, parent_pid: Process.pid)
+      @events = events
+      @interval = interval
+      @probe = probe
+      @parent_pid = parent_pid
+      @workers = {} # pid => seq
+      @lock = Mutex.new
+    end
+
+    # Events listener: follows pids, and samples at each phase boundary.
+    def call(event)
+      fields = event.fields
+      case event.type
+      when :mutant_start then @lock.synchronize { @workers[fields[:pid]] = fields[:seq] }
+      when :mutant_end then @lock.synchronize { @workers.delete(fields[:pid]) }
+      when :phase_start, :phase_end
+        follow_baseline(fields) if fields[:phase] == :baseline
+        tick
+      end
+    end
+
+    # One sample, emitted as a `memory` event. Returns the total in KB (Pss
+    # where the platform has it, else RSS, which overcounts shared pages),
+    # nil when nothing could be read. Public so specs call it directly.
+    def tick
+      workers, baseline_pid = @lock.synchronize { [@workers.dup, @baseline_pid] }
+      readings = @probe.processes([@parent_pid, *workers.keys, baseline_pid].compact)
+      live = workers.filter_map { |pid, seq| readings[pid]&.then { |r| { pid: pid, seq: seq, **sizes(r) } } }
+      baseline = readings[baseline_pid]&.then { |r| { pid: baseline_pid, **sizes(r) } }
+      total = readings.empty? ? nil : readings.each_value.sum { |r| r[:pss_kb] || r[:rss_kb] }
+      @events.emit(:memory, parent: readings[@parent_pid]&.then { |r| sizes(r) }, workers: live,
+                            baseline: baseline, total_pss_kb: total, system: @probe.system)
+      total
+    end
+
+    def start
+      @thread = Thread.new do
+        loop do
+          sleep @interval
+          tick
+        end
+      end
+      self
+    end
+
+    def stop
+      @thread&.kill&.join
+    end
+
+    private
+
+    # phase_start carries the child's pid; phase_end carries none, so it
+    # clears it.
+    def follow_baseline(fields)
+      @lock.synchronize { @baseline_pid = fields[:pid] }
+    end
+
+    def sizes(reading) = reading.slice(:rss_kb, :pss_kb)
+  end
+end