mutant 0.9.5 → 0.9.10

data/Gemfile.shared

@@ -1,3 +1,10 @@
+# Mutant itself uses an opensource license key.
+# Scoped to https://github.com/mbj/mutant it'll
+# not be useful elsewhere.
+source 'https://oss:Px2ENN7S91OmWaD5G7MIQJi1dmtmYrEh@gem.mutant.dev' do
+  gem 'mutant-license'
+end
+
 # Place for shared git sources, used for developing updates to depedencies 
 # where the git sources (without this file) need to be consistently edited 
 # into multiple Gemfiles.

data/README.md

@@ -1,49 +1,80 @@
 mutant
 ======
 
-[![Build Status](https://circleci.com/gh/mbj/mutant.svg?style=shield&circle-token=1afd77e8f0f9d0a11fd8f15f5d7b10270f4665e2)](https://circleci.com/gh/mbj/mutant/tree/master)
+![Build Status](https://github.com/mbj/mutant/workflows/CI/badge.svg)
 [![Gem Version](https://img.shields.io/gem/v/mutant.svg)](https://rubygems.org/gems/mutant)
 [![Slack Status](https://mutation-testing-slack.herokuapp.com/badge.svg)](https://mutation-testing.slack.com/messages/mutant)
 
 ## What is Mutant?
 
-Mutant is a mutation testing tool for Ruby. Mutation testing is a technique to verify semantic coverage of your code.
+An automated code review tool, with a side effect of producing semantic code coverage
+metrics.
 
-## Why do I want it?
+Think of mutant as an expert developer that simplifies your code while making sure that all tests pass.
 
-Mutant adds to your toolbox: Detection of uncovered semantics in your code.
-Coverage becomes a meaningful metric!
+That developer never has a bad day and is always ready to jump on your PR.
 
-On each detection of uncovered semantics you have the opportunity to:
+Each reported simplification signifies either:
 
-* Delete dead code, as you do not want the extra semantics not specified by the tests
-* Add (or improve a test) to cover the unwanted semantics.
-* Learn something new about the semantics of Ruby and your direct and indirect dependencies.
+A) A piece of code that does more than the tests ask for.
+   You can probably use the simplified version of the code. OR:
 
-## How Do I use it?
+B) If you have a reason to not take the simplified version as it violates a requirement:
+   There was no test that proves the extra requirement. Likely you are missing an
+   important test for that requirement.
 
-* Start with reading the [nomenclature](/docs/nomenclature.md) documentation.
+On extensive mutant use A) happens more often than B), which leads to overall less code enter
+your repository at higher confidence for both the author and the reviewer.
+
+BTW: Mutant is a mutation testing tool, which is a form of code coverage.
+But each reported uncovered mutation is actually a call to action, just like a flag in a code review
+would be.
+
+## Getting started:
+
+* Start with reading the [nomenclature](/docs/nomenclature.md). No way around that one, sorry.
 * Then select and setup your [integration](/docs/nomenclature.md#integration), also make sure
   you can reproduce the examples in the integration specific documentation.
-* Identify your preferred mutation testing strategy. It is recommended to start at the commit level,
-  to test only the code you had been touching. See the [incremental](#only-mutating-changed-code)
-  mutation testing documentation.
+* Use mutant during code reviews and on CI in [incremental](/docs/incremental.md) mode.
+* Do not merge code with new alive mutations. If you really must bypass:
+  Add the subjects with open problems to the ignored subjects.
 
 ## Ruby Versions
 
-Mutant currently only works on cRuby/MRI. Starting with version 2.5.x. It supports all syntax features upto and
-including Ruby 2.6.
+Mutant supports multiple ruby versions at different levels. The levels arge staged:
+
+* Runtime, indicates mutant can execute on a specific Ruby Version / implementation.
+* Syntax, depends on Runtime support, and indicates syntax new to that Ruby version can be used.
+* Mutations, depends on Syntax support, and indicates syntax new to that Ruby verison is being analysed.
+
+Supported indicates if a specific Ruby version / Implementation is actively supported. Which means:
+
+* New releases will only be done if all tests pass on supported Ruby versions / implementations.
+* New features will be available.
 
-Support for 2.7 syntax features is pending, see unparser issue: https://github.com/mbj/unparser/issues/129.
+| Implementation | Version        | Runtime            | Syntax             | Mutations          | Supported          |
+| -------------- | -------------- | -------            | ------------------ | ------------------ | ------------------ |
+| cRUBY/MRI      | 2.5            | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: |
+| cRUBY/MRI      | 2.6            | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: |
+| cRUBY/MRI      | 2.7            | :heavy_check_mark: | :soon:             | :soon:             | :heavy_check_mark: |
+| jruby          | TBD            | :email:            | :email:            | :email:            | :email:            |
+| mruby          | TBD            | :email:            | :email:            | :email:            | :email:            |
+| cRUBY/MRI      | < 2.5          | :no_entry:         | :no_entry:         | :no_entry:         | :no_entry:         |
 
-Mutant will work under Ruby 2.7 just fine, unless a 2.7 syntax feature is used. This will be resolved shortly.
+
+Labels:
+
+* :heavy_check_mark: Supported.
+* :soon: Active work in progress.
+* :email: Planned, please contact me on interest.
+* :no_entry: Not being planned, or considered, still contact me on interest.
 
 ## Licensing
 
 Mutant was recently transitioned commercial software, with a free usage plan for opensource projects.
 
 Commercial projects have to acquire a license per developer, with unlimited repositories
-per developer.
+per developer. CI usage for licensed developers is included.
 
 Opensource projects have to acquire their free license per repository.
 
@@ -65,22 +96,52 @@ The mutant license gem contains metadata that allows mutant to verify licensed u
 For commercial licenses mutant checks the git commit author or the configured git email
 to be in the set of licensed developers.
 
-For opensource licenses mutant checks the git remotes against the license whitelist.
+For opensource licenses mutant checks the git remotes against the licensed git repositories.
 This allows the project maintainer to sign up and not bother collaborators with the details.
 
-There are, apart from initial license gem installation, no remote interactions for
+There are, apart from initial license gem installation, no remote interaction for
 license validation.
 
-To inquire for license please contact [Markus Schirp](mailto:mbj@schirp-dso.com?subject=Mutant%20License).
+### Getting an Opensource license
+
+As stated above: Opensource projects of any kind are free to use mutant.
+
+Just mail [me](mailto:mbj@schirp-dso.com?subject=Mutant%20Opensource%20License): Please
+include:
+
+* Just the git remote URL of your repository. Repository can be anywhere, must not be on Github, just has to be public.
+
+I do not need any more details.
+
+### Getting a commercial license
+
+Mutant offers a per developer subscription a monthly plan for 30$, or an annual plan for 300$.
+
+Above 10 developer licensees per customer I'm open to negotiate more discounts.
+
+Should you want to procure a commercial mutant license please [mail me](mailto:mbj@schirp-dso.com?subject=Mutant%20Commercial%20License).
+
+Please include the following information:
+
+* Your invoice address, including your Tax ID (For EU customers VAT-ID is mandatory)
+* Per licensed user the git author email address as returned by `git config user.email`
+
+Also feel free to ask any other question I forgot to proactively answer here.
+
+#### Payment methods
+
+* For monthly subscriptions: Exclusively CC.
+* For annual subscriptions: CC (worldwide) or ACH (US) / SEPA (EU) wire transfer.
 
-### Pricing
+#### Pricing Why?
 
-Only relevant for commercial use.
+The idea is to charge 1$ per developer per day. Mutant reduces the time spend on code reviews.
 
-Mutant offers a subscription model under a monthly plan.
-Yearly prepayments with discounts are available.
+This time saved should be worth way more than the 1$ per day.
 
-For higher volumes different arrangements can be negotiated.
+If you think this is not true for your code base, either my claims are wrong our your use of mutant is wrong.
+I'd be happy to hear about your case as I'm certainly willing to help you in using mutant right, and in case
+I'm wrong I'd be happy to improve mutant to the point I'm right again.
 
 ## Topics
 

data/config/reek.yml

@@ -136,3 +136,4 @@ detectors:
     - Mutant::Reporter::CLI::Printer::StatusProgressive#object # False positive calls super
     - Mutant::Repository::Diff#tracks? # intentional, private
     - Mutant::Repository::Diff#within_working_directory? # intentional, private
+    - Mutant::AST::FindMetaclassContaining#include_exact? # intentional, private

data/lib/mutant.rb

@@ -21,6 +21,7 @@ require 'set'
 require 'singleton'
 require 'stringio'
 require 'unparser'
+require 'variable'
 require 'yaml'
 
 # This setting is done to make errors within the parallel
@@ -50,6 +51,7 @@ require 'mutant/ast/types'
 require 'mutant/ast/nodes'
 require 'mutant/ast/named_children'
 require 'mutant/ast/node_predicates'
+require 'mutant/ast/find_metaclass_containing'
 require 'mutant/ast/meta'
 require 'mutant/ast/meta/send'
 require 'mutant/ast/meta/const'
@@ -111,6 +113,7 @@ require 'mutant/mutator/node/send/conditional'
 require 'mutant/mutator/node/send/attribute_assignment'
 require 'mutant/mutator/node/when'
 require 'mutant/mutator/node/class'
+require 'mutant/mutator/node/sclass'
 require 'mutant/mutator/node/define'
 require 'mutant/mutator/node/mlhs'
 require 'mutant/mutator/node/nthref'
@@ -133,11 +136,13 @@ require 'mutant/subject'
 require 'mutant/subject/method'
 require 'mutant/subject/method/instance'
 require 'mutant/subject/method/singleton'
+require 'mutant/subject/method/metaclass'
 require 'mutant/matcher'
 require 'mutant/matcher/config'
 require 'mutant/matcher/chain'
 require 'mutant/matcher/method'
 require 'mutant/matcher/method/singleton'
+require 'mutant/matcher/method/metaclass'
 require 'mutant/matcher/method/instance'
 require 'mutant/matcher/methods'
 require 'mutant/matcher/namespace'
@@ -160,8 +165,6 @@ require 'mutant/selector/expression'
 require 'mutant/selector/null'
 require 'mutant/config'
 require 'mutant/cli'
-require 'mutant/color'
-require 'mutant/diff'
 require 'mutant/runner'
 require 'mutant/runner/sink'
 require 'mutant/result'
@@ -185,7 +188,6 @@ require 'mutant/reporter/cli/format'
 require 'mutant/repository'
 require 'mutant/repository/diff'
 require 'mutant/repository/diff/ranges'
-require 'mutant/variable'
 require 'mutant/warnings'
 require 'mutant/zombifier'
 require 'mutant/range'

data/lib/mutant/ast.rb

@@ -27,15 +27,6 @@ module Mutant
       path
     end
 
-    # Walk all ast nodes keeping track of path
-    #
-    # @param [Parser::AST::Node] root
-    # @param [Array<Parser::AST::Node>] stack
-    #
-    # @yield [Parser::AST::Node]
-    #   all nodes visited recursively including root
-    #
-    # @return [undefined]
     def self.walk(node, stack, &block)
       block.call(node, stack)
       node.children.grep(::Parser::AST::Node) do |child|

data/lib/mutant/ast/find_metaclass_containing.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Mutant
+  module AST
+    # Given an AST, finds the sclass that directly(-ish) contains the provided
+    # node.
+    # This won't match arbitrarily complex structures - it only searches the
+    # first level deep (no begins-in-begins, for example). This is in
+    # keeping with mutant generally not supporting 'weird' syntax.
+    # Descending into 'begin' nodes is supported because these are generated for
+    # the one-line syntax class << self; def foo; end
+    class FindMetaclassContaining
+      include NodePredicates, Concord.new(:root, :target), Procto.call
+
+      SCLASS_BODY_INDEX = 1
+
+      private_constant(*constants(false))
+
+      # Find metaclass node containing target node
+      #
+      # @return [Parser::AST::Node, nil]
+      #
+      # @api private
+      def call
+        AST.find_last_path(root) do |current|
+          next unless n_sclass?(current)
+
+          metaclass_of?(current)
+        end.last
+      end
+
+    private
+
+      def metaclass_of?(sclass)
+        body = sclass.children.fetch(SCLASS_BODY_INDEX)
+        body.equal?(target) || transparently_contains?(body)
+      end
+
+      def transparently_contains?(body)
+        n_begin?(body) && include_exact?(body.children, target)
+      end
+
+      def include_exact?(haystack, needle)
+        haystack.any? { |elem| elem.equal?(needle) }
+      end
+    end
+  end
+end

data/lib/mutant/ast/meta/send.rb

@@ -56,16 +56,10 @@ module Mutant
 
       private
 
-        # Test if node is `proc { ... }`
-        #
-        # @return [Boolean]
         def naked_proc?
           !receiver && selector.equal?(:proc)
         end
 
-        # Test if node is `Proc.new { ... }`
-        #
-        # @return [Boolean]
         def proc_new?
           receiver                &&
             selector.equal?(:new) &&

data/lib/mutant/bootstrap.rb

@@ -49,9 +49,6 @@ module Mutant
     end
     # rubocop:enable Metrics/MethodLength
 
-    # Infect environment
-    #
-    # @return [undefined]
     def self.infect(env)
       config, world = env.config, env.world
 
@@ -60,12 +57,6 @@ module Mutant
     end
     private_class_method :infect
 
-    # Matchable scopes
-    #
-    # @param [World] world
-    # @param [Config] config
-    #
-    # @return [Array<Scope>]
     def self.matchable_scopes(world, config)
       scopes = world.object_space.each_object(Module).each_with_object([]) do |scope, aggregate|
         expression = expression(config.reporter, config.expression_parser, scope) || next
@@ -76,15 +67,6 @@ module Mutant
     end
     private_class_method :matchable_scopes
 
-    # Scope name from scoping object
-    #
-    # @param [Class, Module] scope
-    #
-    # @return [String]
-    #   if scope has a name and does not raise exceptions obtaining it
-    #
-    # @return [nil]
-    #   otherwise
     def self.scope_name(reporter, scope)
       scope.name
     rescue => exception
@@ -99,20 +81,7 @@ module Mutant
     end
     private_class_method :scope_name
 
-    # Try to turn scope into expression
-    #
-    # @param [Expression::Parser] expression_parser
-    # @param [Class, Module] scope
-    #
-    # @return [Expression]
-    #   if scope can be represented in an expression
-    #
-    # @return [nil]
-    #   otherwise
-    #
     # rubocop:disable Metrics/MethodLength
-    #
-    # ignore :reek:LongParameterList
     def self.expression(reporter, expression_parser, scope)
       name = scope_name(reporter, scope) or return
 
@@ -132,11 +101,6 @@ module Mutant
     private_class_method :expression
     # rubocop:enable Metrics/MethodLength
 
-    # Write a semantics warning
-    #
-    # @return [undefined]
-    #
-    # ignore :reek:LongParameterList
     def self.semantics_warning(reporter, format, options)
       reporter.warn(SEMANTICS_MESSAGE_FORMAT % { message: format % options })
     end

data/lib/mutant/cli.rb

@@ -88,23 +88,12 @@ module Mutant
 
   private
 
-    # Parse matchers
-    #
-    # @param [Array<String>] expressions
-    #
-    # @return [undefined]
     def parse_match_expressions(expressions)
       expressions.each do |expression|
         add_matcher(:match_expressions, config.expression_parser.apply(expression).from_right)
       end
     end
 
-    # Add environmental options
-    #
-    # @param [Object] opts
-    #
-    # @return [undefined]
-    #
     # rubocop:disable Metrics/MethodLength
     def add_environment_options(opts)
       opts.separator('Environment:')
@@ -121,12 +110,8 @@ module Mutant
         with(jobs: Integer(number))
       end
     end
+    # rubocop:enable Metrics/MethodLength
 
-    # Add mutation options
-    #
-    # @param [OptionParser] opts
-    #
-    # @return [undefined]
     def add_mutation_options(opts)
       opts.separator(nil)
       opts.separator('Options:')
@@ -136,11 +121,7 @@ module Mutant
       end
     end
 
-    # Add filter options
-    #
-    # @param [OptionParser] opts
-    #
-    # @return [undefined]
+    # rubocop:disable Metrics/MethodLength
     def add_filter_options(opts)
       opts.on('--ignore-subject EXPRESSION', 'Ignore subjects that match EXPRESSION as prefix') do |pattern|
         add_matcher(:ignore_expressions, config.expression_parser.apply(pattern).from_right)
@@ -154,12 +135,9 @@ module Mutant
         )
       end
     end
+    # rubocop:enable Metrics/MethodLength
 
-    # Add debug options
-    #
-    # @param [OptionParser] opts
-    #
-    # @return [undefined]
+    # rubocop:disable Metrics/MethodLength
     def add_debug_options(opts)
       opts.on('--fail-fast', 'Fail fast') do
         with(fail_fast: true)
@@ -173,38 +151,16 @@ module Mutant
         world.kernel.exit
       end
     end
+    # rubocop:enable Metrics/MethodLength
 
-    # With configuration
-    #
-    # @param [Hash<Symbol, Object>] attributes
-    #
-    # @return [undefined]
     def with(attributes)
       @config = config.with(attributes)
     end
 
-    # Add configuration
-    #
-    # @param [Symbol] attribute
-    #   the attribute to add to
-    #
-    # @param [Object] value
-    #   the value to add
-    #
-    # @return [undefined]
     def add(attribute, value)
       with(attribute => config.public_send(attribute) + [value])
     end
 
-    # Add matcher configuration
-    #
-    # @param [Symbol] attribute
-    #   the attribute to add to
-    #
-    # @param [Object] value
-    #   the value to add
-    #
-    # @return [undefined]
     def add_matcher(attribute, value)
       with(matcher: config.matcher.add(attribute, value))
     end