Class: RuboCop::Cop::Base

Inherits:

Object

Object
RuboCop::Cop::Base

show all

Extended by:: NodePattern::Macros, AST::Sexp, ExcludeLimit

Includes:: AST::Sexp, AutocorrectLogic, IgnoredNode, Util

Defined in:: lib/rubocop/cop/base.rb

Overview

A scaffold for concrete cops.

The Cop::Base class is meant to be extended.

Cops track offenses and can autocorrect them on the fly.

A commissioner object is responsible for traversing the AST and invoking the specific callbacks on each cop.

First the callback on_new_investigation is called; if a cop needs to do its own processing of the AST or depends on something else.

Then callbacks like on_def, on_send (see AST::Traversal) are called with their respective nodes.

Finally the callback on_investigation_end is called.

Within these callbacks, cops are meant to call add_offense or add_global_offense. Use the processed_source method to get the currently processed source being investigated.

In case of invalid syntax / unparsable content, the callback on_other_file is called instead of all the other on_... callbacks.

Private methods are not meant for custom cops consumption, nor are any instance variables.

Direct Known Subclasses

Defined Under Namespace

Classes: InvestigationReport

Constant Summary collapse

RESTRICT_ON_SEND = List of methods names to restrict calls for on_send / on_csend

Set[].freeze

Instance Attribute Summary collapse

#config ⇒ Object readonly

Returns the value of attribute config.
#processed_source ⇒ Object readonly

Returns the value of attribute processed_source.

Class Method Summary collapse

.autocorrect_incompatible_with ⇒ Array<RuboCop::Cop::Cop>

List of cops that should not try to autocorrect at the same time as this cop.
.badge ⇒ Object

Naming.
.callbacks_needed ⇒ Object private
.cop_name ⇒ Object
.department ⇒ Object
.documentation_url ⇒ String^?

Cops (other than builtin) are encouraged to implement this.
.exclude_from_registry ⇒ Object

Call for abstract Cop classes.
.inherited(subclass) ⇒ Object
.joining_forces ⇒ Object

Override and return the Force class(es) you need to join.
.lint? ⇒ Boolean
.match?(given_names) ⇒ Boolean

Returns true if the cop name or the cop namespace matches any of the given names.
.support_autocorrect? ⇒ Boolean

Returns if class supports auto_correct.
.support_multiple_source? ⇒ Boolean

Override if your cop should be called repeatedly for multiple investigations Between calls to on_new_investigation and on_investigation_end, the result of processed_source will remain constant.

Instance Method Summary collapse

#add_global_offense(message = nil, severity: nil) ⇒ Object

Adds an offense that has no particular location.
#add_offense(node_or_range, message: nil, severity: nil, &block) ⇒ Object

Adds an offense on the specified range (or node with an expression) Unless that offense is disabled for this range, a corrector will be yielded to provide the cop the opportunity to autocorrect the offense.
#callbacks_needed ⇒ Object private
#config_to_allow_offenses ⇒ Object
#config_to_allow_offenses=(hash) ⇒ Object
#cop_config ⇒ Object

Configuration Helpers.
#cop_name ⇒ Object (also: #name)
#excluded_file?(file) ⇒ Boolean
#external_dependency_checksum ⇒ Object

This method should be overridden when a cop’s behavior depends on state that lives outside of these locations:.
#initialize(config = nil, options = nil) ⇒ Base constructor

A new instance of Base.
#message(_range = nil) ⇒ Object

Gets called if no message is specified when calling add_offense or add_global_offense Cops are discouraged to override this; instead pass your message directly.
#offenses ⇒ Object deprecated Deprecated.

Make potential errors with previous API more obvious
#on_investigation_end ⇒ Object

Called after all on_…
#on_new_investigation ⇒ Object

Called before all on_…
#on_other_file ⇒ Object

Called instead of all on_…
#parse(source, path = nil) ⇒ Object

There should be very limited reasons for a Cop to do it’s own parsing.
#ready ⇒ Object private

Called between investigations.
#relevant_file?(file) ⇒ Boolean
#target_rails_version ⇒ Object
#target_ruby_version ⇒ Object

Constructor Details

#initialize(config = nil, options = nil) ⇒ `Base`

Returns a new instance of Base.

# File 'lib/rubocop/cop/base.rb', line 71

def initialize(config = nil, options = nil)
  @config = config || Config.new
  @options = options || { debug: false }
  reset_investigation
end

Instance Attribute Details

#config ⇒ `Object` (readonly)

Returns the value of attribute config.



43
44
45

# File 'lib/rubocop/cop/base.rb', line 43

def config
  @config
end

#processed_source ⇒ `Object` (readonly)

Returns the value of attribute processed_source.



43
44
45

# File 'lib/rubocop/cop/base.rb', line 43

def processed_source
  @processed_source
end

Class Method Details

.autocorrect_incompatible_with ⇒ `Array<RuboCop::Cop::Cop>`

List of cops that should not try to autocorrect at the same time as this cop

Returns:

(Array<RuboCop::Cop::Cop>)



59
60
61

# File 'lib/rubocop/cop/base.rb', line 59

def self.autocorrect_incompatible_with
  []
end

.badge ⇒ `Object`

Naming



169
170
171

# File 'lib/rubocop/cop/base.rb', line 169

def self.badge
  @badge ||= Badge.for(name)
end

.callbacks_needed ⇒ `Object`

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

# File 'lib/rubocop/cop/base.rb', line 275

def self.callbacks_needed
  @callbacks_needed ||= public_instance_methods.select do |m|
    m.match?(/^on_|^after_/) &&
      !Base.method_defined?(m) # exclude standard "callbacks" like 'on_begin_investigation'
  end
end

.cop_name ⇒ `Object`



173
174
175

# File 'lib/rubocop/cop/base.rb', line 173

def self.cop_name
  badge.to_s
end

.department ⇒ `Object`



177
178
179

# File 'lib/rubocop/cop/base.rb', line 177

def self.department
  badge.department
end

.documentation_url ⇒ `String`^?

Cops (other than builtin) are encouraged to implement this

Returns:

(String, nil)



67
68
69

# File 'lib/rubocop/cop/base.rb', line 67

def self.documentation_url
  Documentation.url_for(self) if builtin?
end

.exclude_from_registry ⇒ `Object`

Call for abstract Cop classes



157
158
159

# File 'lib/rubocop/cop/base.rb', line 157

def self.exclude_from_registry
  Registry.global.dismiss(self)
end

.inherited(subclass) ⇒ `Object`

# File 'lib/rubocop/cop/base.rb', line 151

def self.inherited(subclass)
  super
  Registry.global.enlist(subclass)
end

.joining_forces ⇒ `Object`

Override and return the Force class(es) you need to join

96	# File 'lib/rubocop/cop/base.rb', line 96 def self.joining_forces; end

.lint? ⇒ `Boolean`

Returns:

(Boolean)



181
182
183

# File 'lib/rubocop/cop/base.rb', line 181

def self.lint?
  department == :Lint
end

.match?(given_names) ⇒ `Boolean`

Returns true if the cop name or the cop namespace matches any of the given names.

Returns:

(Boolean)

# File 'lib/rubocop/cop/base.rb', line 187

def self.match?(given_names)
  return false unless given_names

  given_names.include?(cop_name) || given_names.include?(department.to_s)
end

.support_autocorrect? ⇒ `Boolean`

Returns if class supports auto_correct. It is recommended to extend AutoCorrector instead of overriding

Returns:

(Boolean)



163
164
165

# File 'lib/rubocop/cop/base.rb', line 163

def self.support_autocorrect?
  false
end

.support_multiple_source? ⇒ `Boolean`

Override if your cop should be called repeatedly for multiple investigations Between calls to on_new_investigation and on_investigation_end, the result of processed_source will remain constant. You should invalidate any caches that depend on the current processed_source in the on_new_investigation callback. If your cop does autocorrections, be aware that your instance may be called multiple times with the same processed_source.path but different content.

Returns:

(Boolean)



247
248
249

# File 'lib/rubocop/cop/base.rb', line 247

def self.support_multiple_source?
  false
end

Instance Method Details

#add_global_offense(message = nil, severity: nil) ⇒ `Object`

Adds an offense that has no particular location. No correction can be applied to global offenses

# File 'lib/rubocop/cop/base.rb', line 107

def add_global_offense(message = nil, severity: nil)
  severity = find_severity(nil, severity)
  message = find_message(nil, message)
  @current_offenses <<
    Offense.new(severity, Offense::NO_LOCATION, message, name, :unsupported)
end

#add_offense(node_or_range, message: nil, severity: nil, &block) ⇒ `Object`

Adds an offense on the specified range (or node with an expression) Unless that offense is disabled for this range, a corrector will be yielded to provide the cop the opportunity to autocorrect the offense. If message is not specified, the method message will be called.

# File 'lib/rubocop/cop/base.rb', line 118

def add_offense(node_or_range, message: nil, severity: nil, &block)
  range = range_from_node_or_range(node_or_range)
  return unless current_offense_locations.add?(range)

  range_to_pass = callback_argument(range)

  severity = find_severity(range_to_pass, severity)
  message = find_message(range_to_pass, message)

  status, corrector = enabled_line?(range.line) ? correct(range, &block) : :disabled

  @current_offenses << Offense.new(severity, range, message, name, status, corrector)
end

#callbacks_needed ⇒ `Object`

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.



270
271
272

# File 'lib/rubocop/cop/base.rb', line 270

def callbacks_needed
  self.class.callbacks_needed
end

#config_to_allow_offenses ⇒ `Object`



207
208
209

# File 'lib/rubocop/cop/base.rb', line 207

def config_to_allow_offenses
  Formatter::DisabledConfigFormatter.config_to_allow_offenses[cop_name] ||= {}
end

#config_to_allow_offenses=(hash) ⇒ `Object`



211
212
213

# File 'lib/rubocop/cop/base.rb', line 211

def config_to_allow_offenses=(hash)
  Formatter::DisabledConfigFormatter.config_to_allow_offenses[cop_name] = hash
end

#cop_config ⇒ `Object`

Configuration Helpers

# File 'lib/rubocop/cop/base.rb', line 201

def cop_config
  # Use department configuration as basis, but let individual cop
  # configuration override.
  @cop_config ||= @config.for_badge(self.class.badge)
end

#cop_name ⇒ `Object` Also known as: name



193
194
195

# File 'lib/rubocop/cop/base.rb', line 193

def cop_name
  @cop_name ||= self.class.cop_name
end

#excluded_file?(file) ⇒ `Boolean`

Returns:

(Boolean)



229
230
231

# File 'lib/rubocop/cop/base.rb', line 229

def excluded_file?(file)
  !relevant_file?(file)
end

#external_dependency_checksum ⇒ `Object`

This method should be overridden when a cop’s behavior depends on state that lives outside of these locations:

(1) the file under inspection
(2) the cop's source code
(3) the config (eg a .rubocop.yml file)

For example, some cops may want to look at other parts of the codebase being inspected to find violations. A cop may use the presence or absence of file foo.rb to determine whether a certain violation exists in bar.rb.

Overriding this method allows the cop to indicate to RuboCop’s ResultCache system when those external dependencies change, ie when the ResultCache should be invalidated.



147
148
149

# File 'lib/rubocop/cop/base.rb', line 147

def external_dependency_checksum
  nil
end

#message(_range = nil) ⇒ `Object`

Gets called if no message is specified when calling add_offense or add_global_offense Cops are discouraged to override this; instead pass your message directly



101
102
103

# File 'lib/rubocop/cop/base.rb', line 101

def message(_range = nil)
  self.class::MSG
end

#offenses ⇒ `Object`

Deprecated.

Make potential errors with previous API more obvious

# File 'lib/rubocop/cop/base.rb', line 262

def offenses
  raise 'The offenses are not directly available; ' \
        'they are returned as the result of the investigation'
end

#on_investigation_end ⇒ `Object`

Called after all on_… have been called When refining this method, always call super



85
86
87

# File 'lib/rubocop/cop/base.rb', line 85

def on_investigation_end
  # Typically do nothing here
end

#on_new_investigation ⇒ `Object`

Called before all on_… have been called When refining this method, always call super



79
80
81

# File 'lib/rubocop/cop/base.rb', line 79

def on_new_investigation
  # Typically do nothing here
end

#on_other_file ⇒ `Object`

Called instead of all on_… callbacks for unrecognized files / syntax errors When refining this method, always call super



91
92
93

# File 'lib/rubocop/cop/base.rb', line 91

def on_other_file
  # Typically do nothing here
end

#parse(source, path = nil) ⇒ `Object`

There should be very limited reasons for a Cop to do it’s own parsing



234
235
236

# File 'lib/rubocop/cop/base.rb', line 234

def parse(source, path = nil)
  ProcessedSource.new(source, target_ruby_version, path)
end

#ready ⇒ `Object`

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Called between investigations

# File 'lib/rubocop/cop/base.rb', line 253

def ready
  return self if self.class.support_multiple_source?

  self.class.new(@config, @options)
end

#relevant_file?(file) ⇒ `Boolean`

Returns:

(Boolean)

# File 'lib/rubocop/cop/base.rb', line 223

def relevant_file?(file)
  file == RuboCop::AST::ProcessedSource::STRING_SOURCE_NAME ||
    (file_name_matches_any?(file, 'Include', true) &&
      !file_name_matches_any?(file, 'Exclude', false))
end

#target_rails_version ⇒ `Object`



219
220
221

# File 'lib/rubocop/cop/base.rb', line 219

def target_rails_version
  @config.target_rails_version
end

#target_ruby_version ⇒ `Object`



215
216
217

# File 'lib/rubocop/cop/base.rb', line 215

def target_ruby_version
  @config.target_ruby_version
end

Class: RuboCop::Cop::Base

Overview

Direct Known Subclasses

Defined Under Namespace

Constant Summary collapse

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Methods included from ExcludeLimit

Methods included from AutocorrectLogic

Methods included from IgnoredNode

Methods included from Util

Constructor Details

#initialize(config = nil, options = nil) ⇒ Base

Instance Attribute Details

#config ⇒ Object (readonly)

#processed_source ⇒ Object (readonly)

Class Method Details

.autocorrect_incompatible_with ⇒ Array<RuboCop::Cop::Cop>

.badge ⇒ Object

.callbacks_needed ⇒ Object

.cop_name ⇒ Object

.department ⇒ Object

.documentation_url ⇒ String?

.exclude_from_registry ⇒ Object

.inherited(subclass) ⇒ Object

.joining_forces ⇒ Object

.lint? ⇒ Boolean

.match?(given_names) ⇒ Boolean

.support_autocorrect? ⇒ Boolean

.support_multiple_source? ⇒ Boolean

Instance Method Details

#add_global_offense(message = nil, severity: nil) ⇒ Object

#add_offense(node_or_range, message: nil, severity: nil, &block) ⇒ Object

#callbacks_needed ⇒ Object

#config_to_allow_offenses ⇒ Object

#config_to_allow_offenses=(hash) ⇒ Object

#cop_config ⇒ Object

#cop_name ⇒ Object Also known as: name

#excluded_file?(file) ⇒ Boolean

#external_dependency_checksum ⇒ Object

#message(_range = nil) ⇒ Object

#offenses ⇒ Object

#on_investigation_end ⇒ Object

#on_new_investigation ⇒ Object

#on_other_file ⇒ Object

#parse(source, path = nil) ⇒ Object

#ready ⇒ Object

#relevant_file?(file) ⇒ Boolean

#target_rails_version ⇒ Object

#target_ruby_version ⇒ Object

#initialize(config = nil, options = nil) ⇒ `Base`

#config ⇒ `Object` (readonly)

#processed_source ⇒ `Object` (readonly)

.autocorrect_incompatible_with ⇒ `Array<RuboCop::Cop::Cop>`

.badge ⇒ `Object`

.callbacks_needed ⇒ `Object`

.cop_name ⇒ `Object`

.department ⇒ `Object`

.documentation_url ⇒ `String`^?

.exclude_from_registry ⇒ `Object`

.inherited(subclass) ⇒ `Object`

.joining_forces ⇒ `Object`

.lint? ⇒ `Boolean`

.match?(given_names) ⇒ `Boolean`

.support_autocorrect? ⇒ `Boolean`

.support_multiple_source? ⇒ `Boolean`

#add_global_offense(message = nil, severity: nil) ⇒ `Object`

#add_offense(node_or_range, message: nil, severity: nil, &block) ⇒ `Object`

#callbacks_needed ⇒ `Object`

#config_to_allow_offenses ⇒ `Object`

#config_to_allow_offenses=(hash) ⇒ `Object`

#cop_config ⇒ `Object`

#cop_name ⇒ `Object` Also known as: name

#excluded_file?(file) ⇒ `Boolean`

#external_dependency_checksum ⇒ `Object`

#message(_range = nil) ⇒ `Object`

#offenses ⇒ `Object`

#on_investigation_end ⇒ `Object`

#on_new_investigation ⇒ `Object`

#on_other_file ⇒ `Object`

#parse(source, path = nil) ⇒ `Object`

#ready ⇒ `Object`

#relevant_file?(file) ⇒ `Boolean`

#target_rails_version ⇒ `Object`

#target_ruby_version ⇒ `Object`