mutant 0.15.1 → 0.16.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d4eb76ac40bf4c263a5201b009dbc0760df5191918754bd47452017a4c97ac9b
-  data.tar.gz: b7ed8bb7728602995b796d7950d7c5ed445a3d9e775f7ad69b0dd5e91da3a69f
+  metadata.gz: d35acd82d2b4cf6222613f653da44131636400215c56a14a00f1ecd2ef212079
+  data.tar.gz: ae7ad7d71685be5108bb5fcc6be1b0cae5cd32f56e2848d25467c82d2f72771c
 SHA512:
-  metadata.gz: 27d3948ff6e67c670aefe552fad358d333ee584d48090f13b14d15bee01a756dd6982be5922200dd0d2d939916b9d97e02c862b5d3487c9fd7572688affa544d
-  data.tar.gz: 3155f5599aa51d7d8644fbac0f4f6edb0f2e63d26bd70ca87f20b820f492ba07fa773ec974ad474f3ec08b652acc89eb23033124925c37f933e84eee803f0219
+  metadata.gz: 1481530eb5c56560e06a828086df6d8a5f12d47b3180bafc47f996ccd3a6db22b2cd0ddd213bb12c6934cf878341bad5f987f8cb91113ad0db58a0c68760d203
+  data.tar.gz: 657f62dc386d13f729dfb92fc78afed7c426cd4e64f53ca938c403c6cd4ad06ad856b379dde9d890d2a96ae692f64521975d9d3e0fd850095a4b03ab82d9b906

data/VERSION

@@ -1 +1 @@
-0.15.1
+0.16.0

data/lib/mutant/cli/command/root.rb

@@ -10,7 +10,7 @@ module Mutant
       class Root < self
         NAME              = 'mutant'
         SHORT_DESCRIPTION = 'mutation testing engine main command'
-        SUBCOMMANDS       = [Environment::Run, Environment::Test::Run::Root, Environment, Util].freeze
+        SUBCOMMANDS       = [Environment::Run, Environment::Test::Run::Root, Environment, Session, Util].freeze
       end # Root
     end # Command
   end # CLI

data/lib/mutant/cli/command/session.rb

@@ -0,0 +1,281 @@
+# frozen_string_literal: true
+
+module Mutant
+  module CLI
+    class Command
+      class Session < self
+        NAME              = 'session'
+        SHORT_DESCRIPTION = 'Session history subcommands'
+
+        RESULTS_DIR = '.mutant/results'
+
+      private
+
+        def session_files
+          dir = world.pathname.new(RESULTS_DIR)
+
+          return [] unless dir.directory?
+
+          dir.glob('*.json')
+        end
+
+        def load_session_file(path)
+          world.parse_json(path.read)
+            .bind(&Result::Session::JSON.load_transform.public_method(:call))
+        end
+
+        # Shared base for commands that operate on a session
+        class SessionCommand < self
+          OPTIONS = %i[add_session_id_option].freeze
+
+          UUID_FORMAT = /\A[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\z/
+
+          private_constant(:UUID_FORMAT)
+
+          def display_config
+            @display_config || Reporter::CLI::Printer::DisplayConfig::DEFAULT
+          end
+
+          def action
+            path = resolve_session_path or return Either::Left.new('No sessions found')
+
+            return Either::Left.new("Session file not found: #{path}") unless path.file?
+
+            load_session_file(path).either(
+              lambda { |error|
+ Either::Left.new("Failed to load session: #{error}\nRun `mutant session gc` to remove incompatible sessions.")
+              },
+              method(:run_report)
+            )
+          end
+
+        private
+
+          def add_session_id_option(parser)
+            parser.on('--session-id=ID', 'Session ID to operate on (default: latest)') do |value|
+              fail(OptionParser::InvalidArgument, "invalid UUID format: #{value}") unless UUID_FORMAT.match?(value)
+
+              @session_id = value
+            end
+          end
+
+          def add_verbose_option(parser)
+            parser.separator("\nDisplay Options:\n\n")
+            parser.on('--verbose', 'Show verbose output') do
+              @display_config = Reporter::CLI::Printer::DisplayConfig::VERBOSE
+            end
+          end
+
+          def resolve_session_path
+            if @session_id
+              world.pathname.new("#{RESULTS_DIR}/#{@session_id}.json")
+            else
+              session_files.last
+            end
+          end
+
+          def run_report(session)
+            print("Session:  #{session.session_id}")
+
+            print_report(session)
+          end
+
+          abstract_method :print_report
+        end # SessionCommand
+
+        class List < self
+          NAME              = 'list'
+          SHORT_DESCRIPTION = 'List past mutation testing sessions'
+          SUBCOMMANDS       = [].freeze
+
+          HEADER_FORMAT    = '%-6s  %-10s  %-8s  %-10s  %-10s  %-36s  %s'
+          ROW_FORMAT       = '%-6s  %-10s  %-8s  %-10s  %-10s  %-36s  %s'
+          INCOMPATIBLE = '--------------- [incompatible] ---------------'
+
+          def action
+            print_header
+            session_files.reverse_each(&method(:print_session))
+
+            Either::Right.new(nil)
+          end
+
+        private
+
+          def print_header
+            print(HEADER_FORMAT % ['ALIVE', 'MUTATIONS', 'SUBJECTS', 'RUNTIME', 'KILLTIME', 'SESSION ID', 'TIMESTAMP'])
+          end
+
+          def print_session(path)
+            load_session_file(path).either(
+              ->(_error) { print(colorize_unsupported(path)) },
+              method(:print_session_row)
+            )
+          end
+
+          def print_session_row(session)
+            subjects = session.subject_results
+
+            print(ROW_FORMAT % [
+              subjects.sum(&:amount_mutations_alive),
+              subjects.sum(&:amount_mutations),
+              subjects.length,
+              format_time(session.runtime),
+              format_time(session.killtime),
+              session.session_id,
+              session.timestamp.strftime('%Y-%m-%d %H:%M:%S')
+            ])
+          end
+
+          def format_time(seconds)
+            '%.2fs' % seconds
+          end
+
+          def colorize_unsupported(path)
+            session_id = path.basename('.json')
+
+            Unparser::Color::RED.format(INCOMPATIBLE.ljust(54)) + session_id.to_s
+          end
+        end # List
+
+        class Show < SessionCommand
+          include Mutant::Reporter::CLI::Printer::AliveResults
+
+          NAME              = 'show'
+          SHORT_DESCRIPTION = 'Show results of a past session'
+          SUBCOMMANDS       = [].freeze
+          OPTIONS           = (superclass::OPTIONS + %i[add_verbose_option]).freeze
+
+        private
+
+          def print_report(session)
+            failed = session.subject_results.reject(&:success?)
+
+            print("Time:     #{session.timestamp.strftime('%Y-%m-%d %H:%M:%S')}")
+            print("Version:  #{session.mutant_version}")
+            print("Ruby:     #{session.ruby_version}")
+            print("Subjects: #{session.subject_results.length}")
+            print("Alive:    #{failed.flat_map(&:uncovered_results).length}")
+
+            print_alive_results(failed)
+
+            Either::Right.new(nil)
+          end
+        end # Show
+
+        class Subject < SessionCommand
+          include Mutant::Reporter::CLI::Printer::AliveResults
+
+          NAME              = 'subject'
+          SHORT_DESCRIPTION = 'List subjects or show alive mutations for a specific subject'
+          SUBCOMMANDS       = [].freeze
+          OPTIONS           = (superclass::OPTIONS + %i[add_verbose_option]).freeze
+
+          HEADER_FORMAT = '%-6s  %-6s  %s'
+          ROW_FORMAT    = '%-6s  %-6s  %s'
+
+          def parse_remaining_arguments(arguments)
+            case arguments.length
+            when 0 then Either::Right.new(self)
+            when 1
+              @expression = Mutant::Util.one(arguments)
+              Either::Right.new(self)
+            else
+              Either::Left.new('Expected zero or one subject expression argument')
+            end
+          end
+
+        private
+
+          def print_report(session)
+            if @expression
+              print_subject_detail(session)
+            else
+              print_subject_list(session)
+            end
+          end
+
+          def print_subject_list(session)
+            print(HEADER_FORMAT % %w[ALIVE TOTAL SUBJECT])
+
+            session.subject_results
+              .sort_by { |subject_result| -subject_result.uncovered_results.length }
+              .each(&method(:print_subject_row))
+
+            Either::Right.new(nil)
+          end
+
+          def print_subject_row(subject_result)
+            alive = subject_result.uncovered_results.length
+            total = subject_result.amount_mutations
+
+            print(ROW_FORMAT % [alive, total, subject_result.expression_syntax])
+          end
+
+          def print_subject_detail(session)
+            subject_result = session.subject_results.detect do |subject_result|
+              subject_result.expression_syntax.eql?(@expression)
+            end
+
+            return Either::Left.new("Subject not found: #{@expression}") unless subject_result
+
+            print_alive_results([subject_result])
+
+            Either::Right.new(nil)
+          end
+        end # Subject
+
+        class GC < self
+          NAME              = 'gc'
+          SHORT_DESCRIPTION = 'Remove incompatible and old session results'
+          SUBCOMMANDS       = [].freeze
+          OPTIONS           = %i[add_gc_options].freeze
+
+          DEFAULT_KEEP = 100
+
+          def initialize(*)
+            super
+            @keep = DEFAULT_KEEP
+          end
+
+          def action
+            incompatible, compatible = partition_sessions
+
+            incompatible.each(&:delete)
+
+            excess = compatible.length > @keep ? compatible.first(compatible.length - @keep) : []
+            excess.each(&:delete)
+
+            print("Removed #{incompatible.length + excess.length} session(s)")
+
+            Either::Right.new(nil)
+          end
+
+        private
+
+          def add_gc_options(parser)
+            parser.on('--keep=N', Integer, "Keep N most recent sessions (default: #{DEFAULT_KEEP})") do |value|
+              @keep = value
+            end
+          end
+
+          def partition_sessions
+            incompatible = []
+            compatible   = []
+
+            session_files.each do |path|
+              load_session_file(path).either(
+                ->(_error) { incompatible << path },
+                ->(_session) { compatible << path }
+              )
+            end
+
+            [incompatible, compatible]
+          end
+
+        end # GC
+
+        SUBCOMMANDS = [List, Show, Subject, GC].freeze
+      end # Session
+    end # Command
+  end # CLI
+end # Mutant

data/lib/mutant/cli/command.rb

@@ -220,8 +220,22 @@ module Mutant
         "#{full_name}: #{message}\n\n#{parser}"
       end
 
-      def print(message)
-        world.stdout.puts(message)
+      def output
+        world.stdout
+      end
+
+      def puts(message)
+        output.puts(message)
+      end
+
+      alias_method :print, :puts
+
+      def parse_remaining_arguments(arguments)
+        if arguments.empty?
+          Either::Right.new(self)
+        else
+          Either::Left.new("unexpected arguments: #{arguments.join(' ')}")
+        end
       end
     end # Command
     # rubocop:enable Metrics/ClassLength

data/lib/mutant/config.rb

@@ -120,7 +120,7 @@ module Mutant
           .lmap { |exception| "MUTANT_JOBS environment variable has invalid value: #{jobs.inspect} - #{exception}" }
           .fmap { |jobs_value| DEFAULT.with(jobs: jobs_value) }
       else
-        Either::Right.new(DEFAULT)
+        Either::Right.new(DEFAULT.with(coverage_criteria: CoverageCriteria::EMPTY))
       end
     end
     private_class_method :load_env_config

data/lib/mutant/expression/method.rb

@@ -13,8 +13,6 @@ module Mutant
         :scope_symbol
       )
 
-      private(*anima.attribute_names)
-
       MATCHERS = {
         '.' => [Matcher::Methods::Singleton, Matcher::Methods::Metaclass].freeze,
         '#' => [Matcher::Methods::Instance].freeze

data/lib/mutant/expression/methods.rb

@@ -10,8 +10,6 @@ module Mutant
         :scope_symbol
       )
 
-      private(*anima.attribute_names)
-
       MATCHERS = {
         '.' => [Matcher::Methods::Singleton, Matcher::Methods::Metaclass].freeze,
         '#' => [Matcher::Methods::Instance].freeze

data/lib/mutant/expression/namespace.rb

@@ -6,8 +6,6 @@ module Mutant
     class Namespace < self
       include AbstractType, Anima.new(:scope_name)
 
-      private(*anima.attribute_names)
-
       # Recursive namespace expression
       class Recursive < self
         REGEXP = /\A#{SCOPE_NAME_PATTERN}?\*\z/

data/lib/mutant/isolation/fork.rb

@@ -132,11 +132,7 @@ module Mutant
         def load_result(result_fragments)
           @value = world.marshal.load(result_fragments.join)
         rescue ArgumentError => exception
-          @exception = Exception.new(
-            backtrace:      exception.backtrace,
-            message:        exception.message,
-            original_class: exception.class
-          )
+          @exception = Mutant::Result::Exception.from_exception(exception)
         end
 
         # rubocop:disable Metrics/MethodLength
@@ -197,7 +193,7 @@ module Mutant
         end
 
         def handle_status(status)
-          @process_status = status
+          @process_status = Mutant::Result::ProcessStatus.from_process_status(status)
         end
 
         def peek_child

data/lib/mutant/isolation.rb

@@ -21,6 +21,37 @@ module Mutant
       def valid_value?
         timeout.nil? && exception.nil? && (process_status.nil? || process_status.success?)
       end
+
+      dump = Transform::Success.new(
+        block: lambda do |object|
+          {
+            'exception'      => object.exception && Mutant::Result::Exception::JSON.dump(object.exception).from_right,
+            'log'            => object.log,
+            'process_status' => object.process_status && Mutant::Result::ProcessStatus::JSON.dump(object.process_status).from_right,
+            'timeout'        => object.timeout,
+            'value'          => object.value && Mutant::Result::Test::JSON.dump(object.value).from_right
+          }
+        end
+      )
+
+      load = Transform::Sequence.new(
+        steps: [
+          Transform::Hash.new(
+            required: [
+              Transform::Hash::Key.new(value: 'exception',      transform: Transform::Nullable.new(transform: Mutant::Result::Exception::JSON.load_transform)),
+              Transform::Hash::Key.new(value: 'log',            transform: Transform::STRING),
+              Transform::Hash::Key.new(value: 'process_status', transform: Transform::Nullable.new(transform: Mutant::Result::ProcessStatus::JSON.load_transform)),
+              Transform::Hash::Key.new(value: 'timeout',        transform: Transform::Nullable.new(transform: Transform::FLOAT)),
+              Transform::Hash::Key.new(value: 'value',          transform: Transform::Nullable.new(transform: Mutant::Result::Test::JSON.load_transform))
+            ],
+            optional: []
+          ),
+          Transform::Hash::Symbolize.new,
+          Transform::Success.new(block: method(:new).to_proc)
+        ]
+      )
+
+      JSON = Transform::JSON.new(dump_transform: dump, load_transform: load)
     end # Result
 
     # Call block in isolation

data/lib/mutant/matcher/null.rb

@@ -4,7 +4,7 @@ module Mutant
   class Matcher
     # A null matcher, that does not match any subjects
     class Null < self
-      include Concord.new
+      include Equalizer.new
 
       # Enumerate subjects
       #

data/lib/mutant/mutation/runner/sink.rb

@@ -40,21 +40,30 @@ module Mutant
         # @param [Parallel::Response] response
         #
         # @return [self]
+        # rubocop:disable Metrics/AbcSize
+        # rubocop:disable Metrics/MethodLength
         def response(response)
           fail response.error if response.error
 
-          mutation_result = mutation_result(response.result)
-
-          subject = mutation_result.mutation.subject
+          mutation        = env.mutations.fetch(response.result.mutation_index)
+          subject         = mutation.subject
+          mutation_result = mutation_result(mutation, response.result)
 
           @subject_results[subject] = Result::Subject.new(
-            subject:,
-            coverage_results: previous_coverage_results(subject).dup << coverage_result(mutation_result),
-            tests:            env.selections.fetch(subject)
+            amount_mutations:  subject.mutations.length,
+            coverage_results:  previous_coverage_results(subject).dup << coverage_result(mutation_result),
+            expression_syntax: subject.expression.syntax,
+            identification:    subject.identification,
+            node:              subject.node,
+            source:            subject.source,
+            source_path:       subject.source_path.to_s,
+            tests:             env.selections.fetch(subject)
           )
 
           self
         end
+      # rubocop:enable Metrics/AbcSize
+      # rubocop:enable Metrics/MethodLength
 
       private
 
@@ -65,11 +74,15 @@ module Mutant
           )
         end
 
-        def mutation_result(mutation_index_result)
+        def mutation_result(mutation, mutation_index_result)
           Result::Mutation.new(
-            isolation_result: mutation_index_result.isolation_result,
-            mutation:         env.mutations.fetch(mutation_index_result.mutation_index),
-            runtime:          mutation_index_result.runtime
+            isolation_result:        mutation_index_result.isolation_result,
+            mutation_diff:           mutation.diff.diff,
+            mutation_identification: mutation.identification,
+            mutation_node:           mutation.node,
+            mutation_source:         mutation.source,
+            mutation_type:           mutation.class::SYMBOL,
+            runtime:                 mutation_index_result.runtime
           )
         end
 

data/lib/mutant/mutation/runner.rb

@@ -18,6 +18,7 @@ module Mutant
         env
           .record(:analysis) { run_driver(reporter, async_driver(env)) }
           .tap { |result| env.record(:report) { reporter.report(result) } }
+          .tap { |result| Result::JSONWriter.new(env:, result:).call }
       end
       private_class_method :run_mutation_analysis
 

data/lib/mutant/mutation.rb

@@ -90,15 +90,6 @@ module Mutant
     # @return [String]
     def original_source = subject.source
 
-    # Test if mutation is killed by test reports
-    #
-    # @param [Result::Test] test_result
-    #
-    # @return [Boolean]
-    def self.success?(test_result)
-      self::TEST_PASS_SUCCESS.equal?(test_result.passed)
-    end
-
     # Insert mutated node
     #
     # @param kernel [Kernel]
@@ -126,25 +117,17 @@ module Mutant
 
     # Evil mutation that should case mutations to fail tests
     class Evil < self
-      SYMBOL            = 'evil'
-      TEST_PASS_SUCCESS = false
-
+      SYMBOL = 'evil'
     end # Evil
 
     # Neutral mutation that should not cause mutations to fail tests
     class Neutral < self
-
-      SYMBOL            = 'neutral'
-      TEST_PASS_SUCCESS = true
-
+      SYMBOL = 'neutral'
     end # Neutral
 
     # Noop mutation, special case of neutral
     class Noop < Neutral
-
-      SYMBOL            = 'noop'
-      TEST_PASS_SUCCESS = true
-
+      SYMBOL = 'noop'
     end # Noop
 
   end # Mutation

data/lib/mutant/mutator/node/literal/integer.rb

@@ -11,11 +11,72 @@ module Mutant
 
           children :value
 
+          # Integer overflow boundary probe zones.
+          #
+          # Each entry pairs a zone boundary with a safe prime sentinel
+          # value that falls within that zone. The literal is mutated to
+          # the sentinel of the next zone above its absolute value,
+          # probing whether consuming code handles values that cross the
+          # boundary of the next integer width.
+          #
+          # Safe primes (p = 2q + 1 where both p and q are prime) are
+          # chosen as sentinels because they cannot arise from simple
+          # arithmetic (multiplication, bit shifts, masking), providing
+          # strong guarantees against coincidental mutation kills. A
+          # mutation surviving against a safe prime is a strong signal
+          # of missing boundary validation for that integer width.
+          #
+          # Zone layout:
+          #
+          #   Zone   Boundary  Sentinel
+          #   int8   128       167
+          #   uint8  256       467
+          #   int16  32768     55_487
+          #   uint16 65536     108_503
+          #   int32  2^31      2_667_278_543
+          #   uint32 2^32      7_980_081_959
+          #   int64  2^63      15_508_464_536_481_899_903
+          #
+          # A literal snaps to the next zone above its absolute value.
+          # For example, a literal 100 (below int8 boundary 128) emits
+          # sentinel 167. A literal 200 (above int8, below uint8) emits
+          # sentinel 467. Values at or above 2^63 emit no sentinel as
+          # there is no higher zone to probe.
+          #
+          # Future versions of mutant will add infrastructure to explain
+          # alive mutations, including which overflow zone a surviving
+          # sentinel belongs to and what class of bug it indicates.
+          class OverflowZone
+            include Anima.new(:name, :boundary, :sentinel)
+          end
+
+          OVERFLOW_ZONES = [
+            OverflowZone.new(name: :int8,   boundary: 2**7,  sentinel: 167),
+            OverflowZone.new(name: :uint8,  boundary: 2**8,  sentinel: 467),
+            OverflowZone.new(name: :int16,  boundary: 2**15, sentinel: 55_487),
+            OverflowZone.new(name: :uint16, boundary: 2**16, sentinel: 108_503),
+            OverflowZone.new(name: :int32,  boundary: 2**31, sentinel: 2_667_278_543),
+            OverflowZone.new(name: :uint32, boundary: 2**32, sentinel: 7_980_081_959),
+            OverflowZone.new(name: :int64,  boundary: 2**63, sentinel: 15_508_464_536_481_899_903)
+          ].freeze
+
         private
 
           def dispatch
             emit_singletons
             emit_values
+            emit_overflow_sentinel
+          end
+
+          def emit_overflow_sentinel
+            absolute = value.abs
+
+            OVERFLOW_ZONES.each do |zone|
+              if absolute < zone.boundary
+                emit_type(zone.sentinel)
+                return
+              end
+            end
           end
 
           def values

data/lib/mutant/parallel/connection.rb

@@ -16,8 +16,6 @@ module Mutant
       class Reader
         include Anima.new(:deadline, :io, :marshal, :response_reader, :log_reader)
 
-        private(*anima.attribute_names)
-
         private_class_method :new
 
         attr_reader :log

data/lib/mutant/parallel/driver.rb

@@ -14,8 +14,6 @@ module Mutant
         :workers
       )
 
-      private(*anima.attribute_names)
-
       def initialize(**attributes)
         @alive = true
         super

data/lib/mutant/reporter/cli/printer/alive_results.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Mutant
+  class Reporter
+    class CLI
+      class Printer
+        # Shared logic for printing alive mutation results
+        module AliveResults
+          ALIVE_EXPLANATION = <<~'MESSAGE'
+            Uncovered mutations detected, exiting nonzero!
+            Alive mutations require one of two actions:
+            A) Keep the mutated code: Your tests specify the correct semantics,
+               and the original code is redundant. Accept the mutation.
+            B) Add a missing test: The original code is correct, but the tests
+               do not verify the behavior the mutation removed.
+          MESSAGE
+
+          def print_alive_results(failed_subject_results)
+            failed_subject_results.each do |subject_result|
+              SubjectResult.call(display_config:, output:, object: subject_result)
+            end
+          end
+        end # AliveResults
+      end # Printer
+    end # CLI
+  end # Reporter
+end # Mutant