mutineer 0.2.0

data/lib/mutineer/coverage_map.rb

@@ -0,0 +1,222 @@
+# frozen_string_literal: true
+
+require "open3"
+require "json"
+require "digest"
+require "fileutils"
+require "rbconfig"
+
+module Mutineer
+  # Maps `(source_file, line) -> [test_files]` so each mutant runs only against
+  # the tests that actually exercise its line. Built once (Phase A), then queried
+  # per mutant (Phase B via #tests_for). Persisted to .mutineer/coverage.json with
+  # a content-based digest that rebuilds the map whenever any tracked file changes.
+  #
+  # Keys are "file:line" strings (relative to project_root) everywhere — in
+  # memory and on disk — so load/save needs no key transformation (KTD4).
+  class CoverageMap
+    DEFAULT_CAPTURE_TIMEOUT = 120 # seconds, per coverage subprocess (R3)
+
+    attr_reader :project_root, :failed_test_files, :phase_a_ran
+
+    def initialize(source_paths:, test_paths:, cache_dir: ".mutineer",
+                   load_paths: ["lib"], project_root: Dir.pwd,
+                   capture_timeout: DEFAULT_CAPTURE_TIMEOUT)
+      @source_paths = Array(source_paths)
+      @test_paths   = Array(test_paths)
+      @cache_dir    = cache_dir
+      @load_paths   = Array(load_paths)
+      @project_root = project_root
+      @capture_timeout = capture_timeout
+      @map          = {}
+      @failed_test_files = []
+      @phase_a_ran  = false
+    end
+
+    # Phase A entry point: load the cached map when the content digest matches,
+    # otherwise rebuild from subprocesses and overwrite the cache.
+    def build_or_load
+      warn_external_sources
+      @digest = compute_digest
+
+      cached = read_cache
+      if cached && cached["digest"] == @digest
+        @map = cached["map"] || {}
+        @failed_test_files = cached["failed_test_files"] || []
+        warn_incomplete unless @failed_test_files.empty?
+        return self
+      end
+
+      run_phase_a
+      save
+      self
+    end
+
+    # Phase B lookup: the test files that cover `file:line`, or [] when none do.
+    # ponytail: per-file granularity; upgrade to per-method when throughput
+    # warrants (requires Minitest method isolation + finer Coverage tracking).
+    def tests_for(file, line)
+      @map["#{relativize(file)}:#{line}"] || []
+    end
+
+    private
+
+    def run_phase_a
+      @phase_a_ran = true
+      @map = {}
+      @failed_test_files = []
+
+      @test_paths.each do |test_path|
+        coverage = capture(test_path)
+        next unless coverage
+
+        record(coverage, test_path)
+      end
+    end
+
+    # Spawns a fresh `ruby` reading an inline script from stdin. A fork would
+    # miss already-loaded app lines, so Coverage must start in a clean process
+    # before any source is loaded (KTD1/KTD2). Returns the parsed Coverage.result
+    # hash, or nil when the subprocess failed (logged + skipped per R6).
+    def capture(test_path)
+      out = +""
+      status = nil
+      Open3.popen2(RbConfig.ruby, "-") do |stdin, stdout, wait_thr|
+        stdin.write(subprocess_script(test_path))
+        stdin.close
+        reader = Thread.new { out << stdout.read }
+        # R3: bound the subprocess with a wall clock — a hanging test file must
+        # not wedge the whole run before any per-mutant timeout.
+        unless wait_thr.join(@capture_timeout)
+          Process.kill(:KILL, wait_thr.pid) rescue nil # rubocop:disable Style/RescueModifier
+          reader.kill
+          return fail_test(test_path, "timed out after #{@capture_timeout}s")
+        end
+        reader.join
+        status = wait_thr.value
+      end
+      return fail_test(test_path, "subprocess exited #{status.exitstatus}") unless status.success?
+
+      JSON.parse(out)
+    rescue JSON::ParserError => e
+      fail_test(test_path, "invalid coverage output: #{e.message}")
+    end
+
+    def fail_test(test_path, reason)
+      rel = relativize(test_path)
+      @failed_test_files << rel
+      warn "[mutineer] coverage skipped for #{rel}: #{reason}"
+      nil
+    end
+
+    def subprocess_script(test_path)
+      <<~RUBY
+        require "coverage"
+        require "json"
+        require "stringio"
+        require "minitest"
+        def Minitest.autorun; end
+        Coverage.start(lines: true)
+        $LOAD_PATH.unshift(*#{abs_load_paths.inspect})
+        #{abs_source_paths.inspect}.each { |f| load f }
+        load #{absolute(test_path).inspect}
+        _orig = $stdout
+        $stdout = StringIO.new
+        Minitest.run([])
+        $stdout = _orig
+        puts Coverage.result.to_json
+      RUBY
+    end
+
+    # Records every source line with a non-zero execution count as covered by
+    # this test file. Coverage.result keys are absolute; relativize and drop any
+    # path outside the project (stdlib/gem files).
+    def record(coverage, test_path)
+      rel_test = relativize(test_path)
+      coverage.each do |abs_file, data|
+        rel = relativize(abs_file)
+        next if rel.start_with?("/") # outside project_root — not our source
+
+        counts = data.is_a?(Array) ? data : data["lines"]
+        counts.each_with_index do |count, idx|
+          next unless count&.positive?
+
+          (@map["#{rel}:#{idx + 1}"] ||= []) << rel_test
+        end
+      end
+    end
+
+    # R4: digest each file's ROLE + relative path + content length + content, plus
+    # the load_paths. Without role/path/length delimiters the digest collides
+    # (("ab","c") == ("a","bc")) and is blind to source/test role swaps, silently
+    # accepting a stale cached map.
+    def compute_digest
+      d = Digest::SHA256.new
+      digest_group(d, "source", @source_paths)
+      digest_group(d, "test", @test_paths)
+      @load_paths.sort.each { |lp| d.update("loadpath\0#{lp}\0") }
+      d.hexdigest
+    end
+
+    def digest_group(digest, role, paths)
+      paths.sort.each do |p|
+        content = File.read(absolute(p))
+        digest.update(role)
+        digest.update("\0")
+        digest.update(relativize(absolute(p)))
+        digest.update("\0")
+        digest.update(content.bytesize.to_s)
+        digest.update("\0")
+        digest.update(content)
+        digest.update("\0")
+      end
+    end
+
+    # R7: a configured source that resolves outside project_root would silently be
+    # dropped (its coverage relativizes to an absolute path). Warn instead.
+    def warn_external_sources
+      @source_paths.each do |p|
+        next unless relativize(absolute(p)).start_with?("/")
+
+        warn "[mutineer] source #{p} is outside project root #{@project_root}; " \
+             "its coverage will be ignored"
+      end
+    end
+
+    def cache_path = File.join(@cache_dir, "coverage.json")
+
+    def read_cache
+      return nil unless File.exist?(cache_path)
+
+      JSON.parse(File.read(cache_path))
+    rescue JSON::ParserError
+      nil # corrupt cache — rebuild from scratch
+    end
+
+    def save
+      FileUtils.mkdir_p(@cache_dir)
+      data = { "digest" => @digest, "failed_test_files" => @failed_test_files, "map" => @map }
+      tmp = "#{cache_path}.tmp"
+      File.write(tmp, JSON.generate(data))
+      File.rename(tmp, cache_path) # atomic swap
+    end
+
+    def warn_incomplete
+      warn "[mutineer] cached coverage map may be incomplete; these test files " \
+           "failed to contribute: #{@failed_test_files.join(', ')}"
+    end
+
+    def abs_source_paths = @source_paths.map { |p| absolute(p) }
+    def abs_load_paths   = @load_paths.map { |p| absolute(p) }
+
+    def relativize(path)
+      return path unless path.start_with?("/")
+
+      path.delete_prefix("#{@project_root}/")
+    end
+
+    def absolute(path)
+      File.absolute_path?(path) ? path : File.expand_path(path, @project_root)
+    end
+  end
+end

data/lib/mutineer/isolation.rb

@@ -0,0 +1,157 @@
+# frozen_string_literal: true
+
+require "tempfile"
+require_relative "result"
+require_relative "parser"
+
+module Mutineer
+  # Fork-based isolation for running one mutant. The block runs in a child
+  # process; the parent enforces a wall-clock timeout and decodes the child's
+  # exit status into a Result.
+  #
+  # Exit-status contract (the block's return value, or an explicit exit, is the
+  # child's status): 0 => survived, 1 => killed, 2 => error. Timeout is detected
+  # by the parent's monitor flag, not by status.signaled? (which is true for ANY
+  # signal death, e.g. SIGSEGV — it cannot tell our SIGKILL apart from the OS's).
+  #
+  # mutineer: the 7a strategy this enables (whole-file `load`) re-executes the
+  # entire file — any top-level code runs again. Acceptable for POROs; document
+  # if users hit issues with initializers/callbacks. Upgrade path: M5 strategy
+  # 7b (class_eval surgical redefinition).
+  class Isolation
+    DEFAULT_TIMEOUT = 10 # seconds
+
+    # Runs the block in a forked child. The block's return value (an Integer
+    # exit code) or any explicit `exit` is honoured; an unhandled exception
+    # becomes exit 2 with the cause written to STDERR.
+    def self.run(timeout: DEFAULT_TIMEOUT)
+      pid = fork do
+        code = 0
+        begin
+          result = yield
+          code = result.is_a?(Integer) ? result : 0
+        rescue SystemExit => e
+          code = e.status
+        rescue Exception => e # rubocop:disable Lint/RescueException
+          warn "[mutineer-child] #{e.class}: #{e.message}"
+          code = 2
+        end
+        $stderr.flush
+        # exit! skips at_exit handlers — critical, since a child forked from
+        # inside our own Minitest suite would otherwise re-run the parent's
+        # at_exit autorun hook on the way out.
+        exit!(code)
+      end
+
+      # Single-threaded deadline poll (R2): we are the ONLY caller of waitpid on
+      # this pid, so we never reap-then-kill. We SIGKILL only after WNOHANG shows
+      # the child is still alive past the deadline — so the kill can never hit a
+      # reaped/recycled pid. Timeout is a parent-side fact (deadline reached), not
+      # status.signaled? (which is true for ANY signal death, e.g. SIGSEGV).
+      deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout
+      loop do
+        reaped, status = Process.waitpid2(pid, Process::WNOHANG)
+        return decode(status) if reaped
+
+        if Process.clock_gettime(Process::CLOCK_MONOTONIC) >= deadline
+          Process.kill(:KILL, pid) rescue nil # rubocop:disable Style/RescueModifier
+          Process.waitpid(pid) rescue nil # rubocop:disable Style/RescueModifier
+          return Result.timeout
+        end
+        sleep 0.005
+      end
+    end
+
+    # Strategy 7a (default): write the whole mutated file and `load` it, which
+    # reopens its classes and redefines every method in place. Re-runs file-level
+    # side effects. Child-only — mutates the loaded program.
+    #
+    # The tempfile is created in the ORIGINAL file's directory, not the system
+    # temp dir, so any `require_relative` in the mutated source resolves against
+    # its real neighbours (e.g. a mutator's `require_relative "base"`). Writing it
+    # elsewhere makes those requires resolve to the temp dir and raise LoadError.
+    def self.apply_whole_file(mutated, source_file)
+      Tempfile.create(["mutineer_mutant", ".rb"], File.dirname(source_file)) do |f|
+        f.write(mutated)
+        f.flush
+        load f.path
+      end
+    end
+
+    # Strategy 7b: extract just the enclosing DefNode, apply the mutation to that
+    # snippet, resolve the owner via the namespace path, and class_eval the one
+    # method (KTD6). No file-level side effects re-run. Child-only.
+    #
+    # ponytail: a single owner.class_eval handles BOTH instance and singleton
+    # methods — the extracted snippet keeps its own `def self.x` for singletons,
+    # so class_eval (self == owner) redefines it correctly. Routing singletons
+    # through singleton_class.class_eval (R17) would double-wrap and define on the
+    # wrong class.
+    def self.apply_surgical(mutation, subject, source)
+      loc = subject.def_node.location
+      def_start = loc.start_offset
+      # Byte slicing (C1): Prism offsets are byte offsets.
+      snippet = source.byteslice(def_start...loc.end_offset)
+      rel_s = mutation.start_offset - def_start
+      rel_e = mutation.end_offset - def_start
+      mutated_def = snippet.byteslice(0...rel_s) + mutation.replacement + snippet.byteslice(rel_e..)
+
+      # Rebuild the FULL namespace nesting textually so unqualified enclosing-
+      # namespace constants resolve exactly as a whole-file `load` (7a) would.
+      # class_eval(string) would collapse Module.nesting to [owner] and raise
+      # NameError on such constants (C2 scope-collapse).
+      keywords = nesting_keywords(subject.namespace)
+      prefix   = keywords.map { |kw, name| "#{kw} #{name}" }.join("\n")
+      prefix  += "\n" unless prefix.empty?
+      wrapped  = "#{prefix}#{mutated_def}#{"\nend" * keywords.size}"
+
+      # A snippet that fails to reparse must NOT silently fall through to running
+      # the ORIGINAL method (C2 false-survived). Raise -> the fork block aborts
+      # before any test runs -> Result.error, never a bogus `survived`.
+      raise "surgical snippet failed to reparse" if Parser.parse_string(wrapped).errors.any?
+
+      # Preserve original visibility — class/module bodies define methods public,
+      # but 7a's `load` would re-apply the file's private/protected (C2).
+      owner  = subject.namespace.empty? ? Object : Object.const_get(subject.namespace.join("::"))
+      target = subject.singleton ? owner.singleton_class : owner
+      vis    = method_visibility(target, subject.name)
+
+      # Byte-correct line number; eval at top level so the textual class/module
+      # wrappers rebuild Module.nesting. Offset the lineno by the wrapper prefix
+      # so the def lands on its real source line.
+      def_line = source.byteslice(0, def_start).count("\n") + 1
+      eval_line = [def_line - prefix.count("\n"), 1].max
+      eval(wrapped, TOPLEVEL_BINDING, subject.file, eval_line) # rubocop:disable Security/Eval
+
+      target.send(vis, subject.name) if vis && vis != :public
+    end
+
+    # Resolve each segment of the namespace to its live Module and pick the
+    # correct keyword (reopening a class with `module` — or vice versa — raises
+    # TypeError), so the textual wrapper matches the real definitions.
+    def self.nesting_keywords(namespace)
+      mod = Object
+      namespace.flat_map { |n| n.split("::") }.map do |name|
+        mod = mod.const_get(name)
+        [mod.is_a?(Class) ? "class" : "module", name]
+      end
+    end
+
+    def self.method_visibility(mod, name)
+      return :private   if mod.private_method_defined?(name)
+      return :protected if mod.protected_method_defined?(name)
+      return :public    if mod.public_method_defined?(name)
+
+      nil
+    end
+
+    def self.decode(status)
+      case status.exitstatus
+      when 0 then Result.survived
+      when 1 then Result.killed
+      when 2 then Result.error("child exited with status 2")
+      else        Result.error("unexpected exit status: #{status.exitstatus.inspect}")
+      end
+    end
+  end
+end

data/lib/mutineer/minitest_integration.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require "minitest"
+require "stringio"
+
+module Mutineer
+  # Child-process-only: loads a test file in the current process and runs it
+  # programmatically, returning an exit status integer (0 = all passed,
+  # 1 = any failure/error).
+  #
+  # Never call this in the parent — it manipulates global Minitest state
+  # (autorun, runnables) that only makes sense in a throwaway forked child.
+  #
+  # No `rescue` here: Isolation.run's fork block is the single exception
+  # boundary (any exception there becomes exit 2). Adding a rescue would create
+  # a second exit-2 path and break this method's 0/1 return contract.
+  class MinitestIntegration
+    # ponytail: tested via runner_test.rb (U6), not in isolation — a direct
+    # unit test would require forking and duplicate isolation_test's coverage.
+    #
+    # `test_files` is one path or an Array of paths (M3 coverage selection passes
+    # the covering subset); each is loaded before the single Minitest.run.
+    def self.run(test_files)
+      # Neutralise autorun so a test file's `require "minitest/autorun"`
+      # registers no at_exit hook.
+      def Minitest.autorun; end # rubocop:disable Lint/NestedMethodDefinition
+
+      # Drop runnables inherited from the parent suite (this is the child's
+      # private copy — the parent is unaffected) so only the target test runs.
+      Minitest::Runnable.reset
+
+      Array(test_files).each { |f| load f }
+
+      # Silence the child's test output; the parent only cares about pass/fail.
+      orig = $stdout
+      $stdout = StringIO.new
+      passed = Minitest.run([])
+      $stdout = orig
+
+      passed ? 0 : 1
+    end
+  end
+end

data/lib/mutineer/mutation.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require_relative "parser"
+
+module Mutineer
+  # One atomic byte-range edit. Immutable. One mutation per mutant — never
+  # combine. Source is mutated textually, never regenerated from the AST.
+  Mutation = Data.define(:start_offset, :end_offset, :replacement, :operator) do
+    # Pure: returns a new string, does not mutate `source`. Prism offsets are
+    # BYTE offsets, so all slicing is byte-based (byteslice) — char slicing would
+    # corrupt any source containing a multibyte char before the mutation point.
+    def apply(source)
+      source.byteslice(0, start_offset) + replacement + source.byteslice(end_offset..)
+    end
+
+    # Validity rule: a mutation is valid iff the mutated source re-parses clean.
+    def valid?(source)
+      Parser.parse_string(apply(source)).errors.empty?
+    end
+  end
+end

data/lib/mutineer/mutator_registry.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require_relative "mutators/arithmetic"
+require_relative "mutators/comparison"
+require_relative "mutators/boolean_connector"
+require_relative "mutators/boolean_literal"
+require_relative "mutators/statement_removal"
+require_relative "mutators/return_nil"
+require_relative "mutators/literal_mutation"
+require_relative "mutators/condition_negation"
+
+module Mutineer
+  # Maps operator name -> operator class. DEFAULT_NAMES is the v1 default set
+  # (the M4 Tier-1 + statement-removal operators per locked decision #2). The
+  # three Tier-2 operators live in ALL but are OFF by default — they only run
+  # when named via --operators or `operators:` in .mutineer.yml (KTD8). Keeping
+  # DEFAULT_NAMES an explicit subset (not ALL.keys) is what keeps the M4 default
+  # survivor set unchanged.
+  class MutatorRegistry
+    ALL = {
+      "arithmetic"         => Mutators::Arithmetic,
+      "comparison"         => Mutators::Comparison,
+      "boolean_connector"  => Mutators::BooleanConnector,
+      "boolean_literal"    => Mutators::BooleanLiteral,
+      "statement_removal"  => Mutators::StatementRemoval,
+      "return_nil"         => Mutators::ReturnNil,
+      "literal_mutation"   => Mutators::LiteralMutation,
+      "condition_negation" => Mutators::ConditionNegation
+    }.freeze
+
+    DEFAULT_NAMES = %w[arithmetic comparison boolean_connector boolean_literal statement_removal].freeze
+    TIER2_NAMES   = %w[return_nil literal_mutation condition_negation].freeze
+
+    DESCRIPTIONS = {
+      "arithmetic"         => "+ <-> -, * <-> /, % -> *, ** -> *",
+      "comparison"         => "< <-> <=, > <-> >=, == <-> !=",
+      "boolean_connector"  => "&& <-> ||",
+      "boolean_literal"    => "true <-> false, nil -> true",
+      "statement_removal"  => "replace a non-final statement with nil",
+      "return_nil"         => "replace a return / final expression with nil",
+      "literal_mutation"   => "integer -> 0, 1, n+1; string -> empty",
+      "condition_negation" => "wrap if/unless/ternary condition in !( ... )"
+    }.freeze
+
+    # Returns the operator classes for the given names. Unknown names raise
+    # ArgumentError immediately (caught at the CLI boundary -> exit 2).
+    def self.resolve(names = DEFAULT_NAMES)
+      names.map { |n| ALL.fetch(n) { raise ArgumentError, "Unknown operator: #{n.inspect}" } }
+    end
+
+    def self.default?(name) = DEFAULT_NAMES.include?(name)
+    def self.tier(name)     = TIER2_NAMES.include?(name) ? 2 : 1
+  end
+end

data/lib/mutineer/mutators/arithmetic.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module Mutineer
+  module Mutators
+    # Arithmetic operator: +<->-, *<->/, %->*, **->*. One mutation per
+    # occurrence, rewriting the operator token (CallNode#message_loc).
+    class Arithmetic < Base
+      REPLACEMENTS = {
+        :+ => "-", :- => "+", :* => "/", :/ => "*", :% => "*", :** => "*"
+      }.freeze
+
+      def visit_call_node(node)
+        replacement = REPLACEMENTS[node.name]
+        loc = node.message_loc
+        if replacement && loc
+          @mutations << Mutation.new(
+            start_offset: loc.start_offset,
+            end_offset: loc.end_offset,
+            replacement: replacement,
+            operator: :arithmetic
+          )
+        end
+        super # nested calls (e.g. a + (b * c)) each get their own mutation
+      end
+    end
+  end
+end

data/lib/mutineer/mutators/base.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require "prism"
+require_relative "../mutation"
+
+module Mutineer
+  module Mutators
+    # Base Prism visitor for operators. Subclasses override visit_* methods to
+    # push Mutation objects onto @mutations. Visiting only def_node.body is the
+    # body-only enforcement — the def signature line is never touched.
+    #
+    # ponytail: one implementor in M1; Base earns its keep at M4 when
+    # comparison/boolean operators land and share this contract.
+    class Base < Prism::Visitor
+      def mutations_for(subject, source)
+        @source = source
+        @mutations = []
+        subject.def_node.body&.accept(self)
+        @mutations
+      end
+    end
+  end
+end

data/lib/mutineer/mutators/boolean_connector.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module Mutineer
+  module Mutators
+    # Boolean connector operator: && <-> ||, and <-> or. Replacement is derived
+    # from the actual source token (operator_loc.slice) so symbolic and keyword
+    # forms each map to their own form — never crossing && to `or`, which would
+    # change precedence and surprise the reader (KTD-2).
+    #
+    # Clean-room: from the spec's operator table, not the mutant gem.
+    class BooleanConnector < Base
+      REPLACEMENTS = { "&&" => "||", "||" => "&&", "and" => "or", "or" => "and" }.freeze
+
+      def visit_and_node(node)
+        emit(node)
+        super
+      end
+
+      def visit_or_node(node)
+        emit(node)
+        super
+      end
+
+      private
+
+      def emit(node)
+        loc = node.operator_loc
+        replacement = REPLACEMENTS[loc.slice]
+        return unless replacement
+
+        @mutations << Mutation.new(
+          start_offset: loc.start_offset,
+          end_offset: loc.end_offset,
+          replacement: replacement,
+          operator: :boolean_connector
+        )
+      end
+    end
+  end
+end

data/lib/mutineer/mutators/boolean_literal.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module Mutineer
+  module Mutators
+    # Mutates true/false AND nil literals — "boolean_literal" is the spec's name
+    # for the family (§4), so nil is in-scope by design even though it is not
+    # strictly a boolean. true<->false, and nil->true (nil->true catches more
+    # return-value gaps than nil->false). Rewrites the whole node location;
+    # these nodes have no sub-token location.
+    #
+    # Clean-room: from the spec's operator table, not the mutant gem.
+    class BooleanLiteral < Base
+      def visit_true_node(node)
+        emit(node, "false")
+        super
+      end
+
+      def visit_false_node(node)
+        emit(node, "true")
+        super
+      end
+
+      def visit_nil_node(node)
+        emit(node, "true")
+        super
+      end
+
+      private
+
+      def emit(node, replacement)
+        loc = node.location
+        @mutations << Mutation.new(
+          start_offset: loc.start_offset,
+          end_offset: loc.end_offset,
+          replacement: replacement,
+          operator: :boolean_literal
+        )
+      end
+    end
+  end
+end

data/lib/mutineer/mutators/comparison.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module Mutineer
+  module Mutators
+    # Comparison / boundary operator: <->-<=, >->-=>, ==->!=, etc. The single
+    # highest-value Tier-1 family (spec §4) — exposes off-by-one and boundary
+    # gaps line coverage never catches. Rewrites the operator token
+    # (CallNode#message_loc), one mutation per occurrence.
+    #
+    # Clean-room: implemented from the spec's operator table and public
+    # mutation-testing literature, not the mutant gem.
+    class Comparison < Base
+      REPLACEMENTS = {
+        :< => "<=", :<= => "<", :> => ">=", :>= => ">", :== => "!=", :!= => "=="
+      }.freeze
+
+      def visit_call_node(node)
+        replacement = REPLACEMENTS[node.name]
+        loc = node.message_loc
+        # receiver guard: reject any unary call accidentally named like an
+        # operator; binary comparisons always have a receiver.
+        if replacement && loc && node.receiver
+          @mutations << Mutation.new(
+            start_offset: loc.start_offset,
+            end_offset: loc.end_offset,
+            replacement: replacement,
+            operator: :comparison
+          )
+        end
+        super # nested comparisons (a >= b && c <= d) each get their own mutation
+      end
+    end
+  end
+end