rubocop-magic_numbers 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 4db321fec029b7e924bda74c35c9f9dcfdd902173d31965fad3ca07507ef606b
+  data.tar.gz: f477370605f885adfd7a1353a6065c637226ff4b637001546b4b2e4109787bde
+SHA512:
+  metadata.gz: 408cb1f1488a6e57063a57b7422dc74145334c3c296e7d3dd129e1e7447c5e309df13040b7aae1d258294b21026e81ff586e4c9754f7af2be31b916343690a10
+  data.tar.gz: 4020f1a2891c85d1f0ed3c13acffb47e10a3213d073335d907a1d53f2faeaf912b631a80b332a443b3e2e6fc8da93f54a6958ca5e72590c34dd66d2ef00bcf50

data/README.md

@@ -0,0 +1,63 @@
+# rubocop-magic_numbers
+
+![Ruby tests](https://github.com/bodacious/rubocop-magic_numbers/actions/workflows/ruby.yml/badge.svg)
+![RuboCop Lint](https://github.com/bodacious/rubocop-magic_numbers/actions/workflows/rubocop.yml/badge.svg)
+
+
+`rubocop-magic_numbers` is a gem that detects the use of magic numbers within Ruby code and raises them as offenses.
+
+Magic numbers are typically integers or floats that are used within code with no descriptive context to help other developers understand what they represent. To write cleaner and more maintainable code, it is recommended to assign the numbers to constants with helpful names.
+
+``` ruby
+# BAD
+def calculate_annual_earnings
+  pay_per_shift = 50.0
+  pay_per_shift * 5 * 52
+end
+
+# GOOD
+PAY_PER_SHIFT = 50.0
+SHIFTS_PER_WEEK = 5
+WEEKS_PER_YEAR = 52
+def calculate_annual_earnings
+  PAY_PER_SHIFT * SHIFTS_PER_WEEK * WEEKS_PER_YEAR
+end
+```
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'rubocop-magic_numbers', require: false, group: :development
+```
+
+And then execute:
+
+```bash
+$ bundle install
+```
+
+## Usage
+
+After installing the gem, `rubocop` should automatically detect and raise offenses for magic numbers within your code. You can customize the behavior of the gem by adding configurations to a `.rubocop.yml` file in your project's root directory.
+
+Here are some examples of configurations you can use:
+
+```yaml
+require:
+  - rubocop-magic_numbers
+
+# TODO
+# define configs here
+```
+
+For more information on configuring `rubocop`, please refer to the [official documentation](https://docs.rubocop.org/rubocop/configuration.html).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/bodacious/rubocop-magic_numbers. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](https://www.contributor-covenant.org/) code of conduct.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/lib/rubocop/cop/magic_numbers/base.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require 'rubocop/cop/cop'
+
+module RuboCop
+  module Cop
+    module MagicNumbers
+      # Base class for all shared behaviour between these cops
+      class Base < ::RuboCop::Cop::Cop
+        CONFIG_ALL = 'All'
+        CONFIG_FLOAT = 'Float'
+        CONFIG_INTEGER = 'Integer'
+        CONFIG_NAME_FORBIDDEN_NUMERICS = 'ForbiddenNumerics'
+
+        DEFAULT_CONFIG = {
+          CONFIG_NAME_FORBIDDEN_NUMERICS => CONFIG_ALL
+        }.freeze
+
+        ILLEGAL_SCALAR_TYPES = {
+          CONFIG_ALL => %i[float int],
+          CONFIG_INTEGER => %i[int],
+          CONFIG_FLOAT => %i[float]
+        }.freeze
+
+        # The configuration for this cop, pre-set with defaults
+        #
+        # Returns Hash
+        def cop_config
+          DEFAULT_CONFIG.merge(super)
+        end
+
+        private
+
+        # The AST pattern for the configured ForbiddenNumerics types.
+        #
+        # Examples
+        #
+        #   "{float int}"
+        #
+        # Returns String
+        def illegal_scalar_pattern
+          "{#{forbidden_numerics.join(' ')}}"
+        end
+
+        # The numeric types that are forbidden based on this cop's configuration
+        #
+        # Returns Array of Symbols
+        def forbidden_numerics
+          forbidden_numerics_key = cop_config[CONFIG_NAME_FORBIDDEN_NUMERICS]
+          ILLEGAL_SCALAR_TYPES[forbidden_numerics_key]
+        end
+
+        # Check if the given AST node matches the given pattern
+        #
+        # node    - A RuboCop::AST::ProcessedSource
+        # pattern - A RuboCop::AST::NodePattern
+        #
+        # Returns Boolean
+        def node_matches_pattern?(node:, pattern:)
+          RuboCop::AST::NodePattern.new(pattern).match(node)
+        end
+
+        # Check if the given AST node is within a method definition
+        #
+        # node    - A RuboCop::AST::ProcessedSource
+        #
+        # Returns Boolean
+        def node_within_method?(node)
+          node.ancestors.any?(&:def_type?)
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/cop/magic_numbers/no_argument.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module RuboCop
+  module Cop
+    module MagicNumbers
+      # Adds violations for magic numbers when used as the argument to a method
+      #
+      # BAD:
+      # object.bottles_on_the_wall(100)
+      #
+      # GOOD:
+      # object.bottles_on_the_wall(DEFAULT_BOTTLE_COUNT)
+      class NoArgument < Base
+        MAGIC_NUMBER_ARGUMENT_PATTERN = <<-PATTERN
+          (send
+            {
+              _
+              _
+              (%<illegal_scalar_pattern>s _)
+              | # This is a union of lhs and rhs literal
+              (%<illegal_scalar_pattern>s _)
+              _
+              _
+            }
+          )
+        PATTERN
+
+        ARGUMENT_MSG = 'Do not use magic number arguments to methods'
+
+        CONFIG_IGNORED_METHODS_NAME = 'IgnoredMethods'
+
+        # By default, don't raise an offense for magic numbers arguments
+        # for these methods
+        DEFAULT_CONFIG = {
+          CONFIG_IGNORED_METHODS_NAME => ['[]']
+        }.freeze
+
+        def cop_config
+          super.merge(DEFAULT_CONFIG)
+        end
+
+        def on_message_send(node)
+          return unless illegal_argument?(node)
+          return if ignored_method?(node)
+
+          add_offense(node, location: :expression, message: ARGUMENT_MSG)
+        end
+        alias on_send on_message_send # rubocop API method name
+
+        private
+
+        def ignored_method?(node)
+          return false unless node.respond_to?(:method_name)
+
+          ignored_methods.include?(node.method_name)
+        end
+
+        def ignored_methods
+          Array(cop_config[CONFIG_IGNORED_METHODS_NAME]).map(&:to_sym)
+        end
+
+        def illegal_argument?(node)
+          node_matches_pattern?(
+            node:,
+            pattern: format(
+              MAGIC_NUMBER_ARGUMENT_PATTERN,
+              illegal_scalar_pattern:
+            )
+          )
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/cop/magic_numbers/no_assignment.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module RuboCop
+  module Cop
+    module MagicNumbers
+      # Adds violations for magic numbers, aka assignments to variables with
+      # bare numbers, configurable by literal type. Can detect local, instance,
+      # global, and setter assignment, and works on multiple assignment.
+      #
+      # bad: hours = 24
+      #
+      # good: HOURS_IN_ONE_DAY = 24
+      class NoAssignment < Base
+        MAGIC_NUMBER_ARGUMENT_TO_SETTER_PATTERN = <<-PATTERN
+          (send
+            ({send self} ...)
+            $_
+            (%<illegal_scalar_pattern>s _)
+          )
+        PATTERN
+
+        MAGIC_NUMBER_MULTI_ASSIGN_PATTERN = <<-PATTERN
+          (masgn
+            (mlhs ({lvasgn ivasgn send} ...)+)
+            (array <(%<illegal_scalar_pattern>s _) ...>)
+          )
+        PATTERN
+        LOCAL_VARIABLE_ASSIGN_MSG = 'Do not use magic number local variables'
+        INSTANCE_VARIABLE_ASSIGN_MSG = 'Do not use magic number instance variables'
+        MULTIPLE_ASSIGN_MSG = 'Do not use magic numbers in multiple assignments'
+        PROPERTY_MSG = 'Do not use magic numbers to set properties'
+        DEFAULT_CONFIG = {
+          'AllowedAssignments' => %w[class_variables global_variables]
+        }.freeze
+
+        def cop_config
+          DEFAULT_CONFIG.merge(super)
+        end
+
+        def on_local_variable_assignment(node)
+          return unless illegal_scalar_value?(node)
+          return unless node_within_method?(node)
+
+          add_offense(node, location: :expression, message: LOCAL_VARIABLE_ASSIGN_MSG)
+        end
+        alias on_lvasgn on_local_variable_assignment # rubocop API method name
+
+        def on_instance_variable_assignment(node)
+          return unless illegal_scalar_value?(node)
+          return unless node_within_method?(node)
+
+          add_offense(node, location: :expression, message: INSTANCE_VARIABLE_ASSIGN_MSG)
+        end
+        alias on_ivasgn on_instance_variable_assignment # rubocop API method name
+
+        def on_message_send(node)
+          return unless illegal_scalar_argument_to_setter?(node)
+          return unless node_within_method?(node)
+
+          add_offense(node, location: :expression, message: PROPERTY_MSG)
+        end
+        alias on_send on_message_send # rubocop API method name
+
+        def on_multiple_assign(node)
+          # multiassignment nodes aren't AsgnNode typed, so we need to have a
+          # special approach to deconstruct them and assess if they contain magic
+          # numbers amongst their assignments
+          return false unless illegal_multi_assign_right_hand_side?(node)
+
+          add_offense(node, location: :expression, message: MULTIPLE_ASSIGN_MSG)
+        end
+        alias on_masgn on_multiple_assign
+
+        private
+
+        def illegal_scalar_argument_to_setter?(node)
+          method = node_matches_pattern?(
+            node:,
+            pattern: format(
+              MAGIC_NUMBER_ARGUMENT_TO_SETTER_PATTERN,
+              illegal_scalar_pattern:
+            )
+          )
+
+          method&.end_with?('=')
+        end
+
+        def illegal_multi_assign_right_hand_side?(node)
+          node_matches_pattern?(
+            node:,
+            pattern: format(
+              MAGIC_NUMBER_MULTI_ASSIGN_PATTERN,
+              illegal_scalar_pattern:
+            )
+          )
+        end
+
+        def illegal_scalar_value?(node)
+          return false unless node.assignment?
+
+          # multiassignment nodes contain individual assignments in their AST
+          # representations, but they aren't aware of their values, so we need to
+          # allow for expressionless assignments
+          forbidden_numerics.include?(node.expression&.type)
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/cop/magic_numbers/no_default.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module RuboCop
+  module Cop
+    module MagicNumbers
+      # Adds violations for magic numbers, when used as default values for
+      # arguments to methods
+      #
+      # BAD
+      # def on_the_wall(bottles = 100)
+      #
+      # GOOD
+      # def on_the_wall(bottles = DEFAULT_BOTTLE_COUNT)
+      class NoDefault < Base
+        MAGIC_NUMBER_OPTIONAL_ARGUMENT_PATTERN = <<-PATTERN
+          (def
+            _
+            (args
+              <({kwoptarg optarg}
+                _
+                (%<illegal_scalar_pattern>s _)
+              ) ...>
+            )
+            ...
+          )
+        PATTERN
+
+        DEFAULT_OPTIONAL_ARGUMENT_MSG = 'Do not use magic number optional ' \
+                                        'argument defaults'
+
+        def on_method_defined(node)
+          return unless illegal_positional_default?(node)
+
+          add_offense(
+            node,
+            location: :expression,
+            message: DEFAULT_OPTIONAL_ARGUMENT_MSG
+          )
+        end
+        alias on_def on_method_defined # rubocop API method name
+
+        private
+
+        def illegal_positional_default?(node)
+          node_matches_pattern?(
+            node:,
+            pattern: format(
+              MAGIC_NUMBER_OPTIONAL_ARGUMENT_PATTERN,
+              illegal_scalar_pattern:
+            )
+          )
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/cop/magic_numbers/no_return.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module RuboCop
+  module Cop
+    module MagicNumbers
+      # Raises an offense if a method returns with a magic number
+      # Catches both explicit and implicit returns
+      class NoReturn < Base
+        MAGIC_NUMBER_RETURN_PATTERN = <<~PATTERN.chomp
+          (%<illegal_scalar_pattern>s _)
+        PATTERN
+        NO_EXPLICIT_RETURN_MSG = 'Do not return magic numbers from a method or proc'
+
+        CONFIG_NAME_ALLOWED_RETURNS = 'AllowedReturns'
+
+        RETURN_TYPE_IMPLICIT = 'Implicit'
+        RETURN_TYPE_EXPLICIT = 'Explicit'
+        RETURN_TYPE_NONE = 'None'
+
+        # Supported values are 'Explicit', 'Implicit', 'None'
+        DEFAULT_CONFIG = {
+          CONFIG_NAME_ALLOWED_RETURNS => [RETURN_TYPE_NONE]
+        }.freeze
+
+        def cop_config
+          super.merge(DEFAULT_CONFIG)
+        end
+
+        def on_method_defined(node)
+          return if allowed_returns.include?(RETURN_TYPE_IMPLICIT)
+          return unless implicit_return?(node.children.last)
+
+          add_offense(node.children.last, location: :expression, message: NO_EXPLICIT_RETURN_MSG)
+        end
+        alias on_def on_method_defined
+
+        def on_return(node)
+          return if allowed_returns.include?(RETURN_TYPE_EXPLICIT)
+          return unless forbidden_numerics.include?(node.children.first&.type)
+
+          add_offense(node.children.first, location: :expression, message: NO_EXPLICIT_RETURN_MSG)
+        end
+
+        private
+
+        def allowed_returns
+          Array(cop_config[CONFIG_NAME_ALLOWED_RETURNS])
+        end
+
+        def implicit_return?(node)
+          is_node_begin_type = node.is_a?(RuboCop::AST::Node) && node.begin_type?
+          return implicit_return?(node.children.last) if is_node_begin_type
+
+          pattern = format(MAGIC_NUMBER_RETURN_PATTERN, {
+                             illegal_scalar_pattern:
+                           })
+          node_matches_pattern?(node:, pattern:)
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/magic_numbers/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module MagicNumbers
+    VERSION = '0.1.0'
+  end
+end

data/lib/rubocop/magic_numbers.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require 'rubocop/magic_numbers/version'
+require 'rubocop/cop/magic_numbers/base'
+require 'rubocop/cop/magic_numbers/no_argument'
+require 'rubocop/cop/magic_numbers/no_assignment'
+require 'rubocop/cop/magic_numbers/no_default'
+require 'rubocop/cop/magic_numbers/no_return'

metadata

@@ -0,0 +1,84 @@
+--- !ruby/object:Gem::Specification
+name: rubocop-magic_numbers
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Gavin Morrice
+- Fell Sunderland
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2023-06-19 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: parser
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: rubocop/magic_numbers implements a rubocop cop for detecting the use
+  of bare numbers when linting
+email:
+- gavin@gavinmorrice.com
+- fell@meetcleo.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/rubocop/cop/magic_numbers/base.rb
+- lib/rubocop/cop/magic_numbers/no_argument.rb
+- lib/rubocop/cop/magic_numbers/no_assignment.rb
+- lib/rubocop/cop/magic_numbers/no_default.rb
+- lib/rubocop/cop/magic_numbers/no_return.rb
+- lib/rubocop/magic_numbers.rb
+- lib/rubocop/magic_numbers/version.rb
+homepage: https://github.com/Bodacious/rubocop-magic_numbers
+licenses:
+- MIT
+metadata:
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.6
+signing_key:
+specification_version: 4
+summary: rubocop/magic_numbers implements a rubocop cop for detecting the use of bare
+  numbers when linting
+test_files: []