dark_finger 0.3.1 → 0.6.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 2c5b4a2b9fd64fc712fe87e8217705c9fc10fb37
-  data.tar.gz: 01cf3213671f4e9a18ad2e355b549dc5ee38ab06
+SHA256:
+  metadata.gz: c387170753bd389d4df0457821fa9e56bf06f1d609e73ea2b4864753e9e09816
+  data.tar.gz: 12946aef0ce96a285a69714a8bb5f830335b47c4509b69151734a8523df76fea
 SHA512:
-  metadata.gz: 256aea1e41241022db13ec4c7f7dabdcd7eeeb878a96282833ab63b679c0411c4d8db2dd193116847c8d42d6f96ebf78c14c4ff152f46d93d01137f8bf917f10
-  data.tar.gz: 5a74ed3a93cbdb4951fa3b98acb9b7a4d37581452c04fc651009298ff0b3011abae28bf87915c80b6fdb3acc2bc6eaab981dbbdd93067f621fd3f4a3dff0b46a
+  metadata.gz: 0db6984e3639dd26fd5db716e94055dcbe481fb89fc947778f8b34a250b2b0fd042ab710ba5b6bba1351b1c5fde2e4dcb3d73234c4eae77ab5dc87d407b9b2c0
+  data.tar.gz: 334320e100727d04675b0cdc3cbf92d9ce597783090fe78d4e2ab08d379567412e8667d93981408c66c87edf86df416d42e17a4f66d5c2461688226c69044fbb

data/.gitignore

@@ -8,3 +8,4 @@
 /spec/reports/
 /tmp/
 tags
+vendor/

data/README.md

@@ -1,23 +1,13 @@
-# DarkFinger
+![Dark Finger](.github/dark_finger.jpg "Dark Finger")
 
-A Rubocop extension to check the layout of ActiveModel files. The cop will
-check that elements appear together, in the right order, and commented as
-desired.
+A Rubocop extension containing two cops:
 
-Supported elements:
-
-* associations
-* attributes
-* callbacks
-* constants
-* enums
-* includes
-* modules
-* scopes
-* validations
-* class_methods
-* instance_methods
+1. [Model Structure](docs/model_structure.md). Keep those "macro" methods at the top
+   of your model files clean and consistent across the project.
 
+2. [Migration Constants](docs/migration_constants.md). Prevent a common source of
+   migration breakage - dependencies on things that are likely to change by the
+   time the migration is actually run.
 
 ## Installation
 
@@ -37,45 +27,7 @@ Or install it yourself as:
 
 ## Usage
 
-Install the gem. Then, in your `.rubycop.yml` file, require `dark_finger` and
-add your desired config.
-
-For example, here is the default config:
-
-```ruby
-# in .rubocop.yml
-
-
-# this is required
-require: dark_finger
-
-DarkFinger/ModelStructure:
-  Include:
-    - 'app/models/*'
-  required_order:
-    - module
-    - include
-    - enum
-    - constant
-    - association
-    - validation
-    - scope
-    - attributes
-    - callback
-    - class_method
-    - instance_method
-  required_comments:
-    association: '# Relationships'
-    attribute: '# Attributes'
-    callback: '# Callbacks'
-    constant: '# Constants'
-    enum: '# Enums'
-    include: '# Includes'
-    module: '# Modules'
-    scope: '# Scopes'
-    validation: '# Validations'
-
-```
+See the guides for each of the Cops for details.
 
 ## License
 

data/docs/migration_constants.md

@@ -0,0 +1,62 @@
+# The Migration Constants Cop
+
+In our rails migration files we don't want dependencies on, for example,
+ActiveRecord model files.
+
+This is because migration files should be "timeless" and able to run at any
+point in the future. Our model files change very frequently - and therefore
+cannot be depended on directly. We must redeclare the model inside the
+migration file.
+
+For example:
+
+```ruby
+  # BAD :'(
+  #
+  # This migration depends on `SomeModel` and `.some_scope`. When this
+  # migration is actually run, either of those things could have changed name,
+  # or perhaps `some_scope` might behave differently by then or have been
+  # deleted.
+  class FooMigration < ActiveRecord::Migration[5.1]
+    def up
+      SomeModel.some_scope.each do
+        # stuff
+      end
+    end
+  end
+
+  # GOOD :-D
+  #
+  # This migration has no external dependencies on our app. It is unlikely to
+  # break in the future as our app changes.
+  class FooMigration < ActiveRecord::Migration[5.1]
+    class SomeModel < ActiveRecord::Base
+      scope :some_scope, -> { ... }
+    end
+
+    def up
+      SomeModel.some_scope.each do
+        # stuff
+      end
+    end
+  end
+```
+
+This cop will issue warnings if a migration file depends on certain constants
+(like model files) that it doesn't declare.
+
+## Usage
+
+Install the gem and then add this to your `.rubocop.yml` file:
+
+```yaml
+# this is required
+require: dark_finger
+
+DarkFinger/MigrationConstants:
+  Include:
+    - 'db/migrate/*.rb'
+  whitelisted_constants:
+    - 'MyConstant'
+    - 'MyOtherConstant'
+```

data/docs/model_structure.md

@@ -0,0 +1,145 @@
+# The Model Structure Cop
+
+At work we've found that, as our model files grow in size, there are many
+"macro" methods (scopes, validations, etc) at the top that become messy and
+inconsistent across files.
+
+This cop will issue warnings if the various model elements:
+
+1. Aren't grouped together
+2. The groups don't appear in the right order
+3. The groups aren't commented properly
+
+This is the kind of model file that we like. Notice how all the model elements
+are grouped, commented, and ordered (although ordering is not visible from just
+one file):
+
+```ruby
+class Horse < ApplicationRecord
+  ## Includes ##
+  include GallopingMagicPowers
+  include LazerEyes
+
+  ## Enums ##
+  enum breed: %i[thoroughbred
+                 arabian
+                 american quarter horse
+                 clydesdale
+                 mustang]
+
+  ## Associations ##
+  has_many :legs
+  belongs_to :brain
+  belongs_to :saddle
+
+  ## Validations ##
+  validates_presence_of :breed
+  validates_presence_of :age
+
+  ## Scopes ##
+  scope :dead, -> { where(state: 'dead') }
+  scope :alive, -> { where(state: 'alive') }
+
+  ## Attributes ##
+  attr_accessor :promote_to_demon_horse
+
+  ## Callbacks ##
+  after_save :callbacks_are_evil_you_should_be_ashamed
+
+  ## Misc ##
+  serialize :nose_hairs, Array
+  acts_as_taggable
+
+  def self.foobario
+    # foo
+  end
+
+  def gallop_hard
+    # ...
+  end
+end
+
+```
+
+## Usage and Configuration
+
+Install the gem. Then, in your `.rubycop.yml` file, require `dark_finger` and
+add your desired config.
+
+For example:
+
+```yaml
+# in .rubocop.yml
+
+# this is required
+require: dark_finger
+
+DarkFinger/ModelStructure:
+
+  # this is also required
+  Include:
+    - 'app/models/*'
+
+  # specify the order that the model elements must appear in
+  required_order:
+    - module
+    - include
+    - enum
+    - constant
+    - association
+    - validation
+    - scope
+    - attributes
+    - callback
+    - misc
+    - constructor
+    - class_method
+    - instance_method
+
+  # specify the comments that must appear above each group of model elements
+  required_comments:
+    association: '## Relationships ##'
+    attribute: '## Attributes ##'
+    callback: '## Callbacks ##'
+    constant: '## Constants ##'
+    enum: '## Enums ##'
+    include: '## Includes ##'
+    misc: '## Misc ##'
+    module: '## Modules ##'
+    scope: '## Scopes ##'
+    validation: '## Validations ##'
+
+  # specify the methods that are categorized as "misc"
+  misc_method_names:
+    - acts_as_list
+    - acts_as_taggable
+    - friendly_id
+    - serialize
+    - workflow
+```
+
+Supported model elements:
+
+
+| Config key      | Description (when not obvious)             |
+|-----------------|--------------------------------------------|
+| association     |                                            |
+| attribute       | `attr_reader` and friends                  |
+| callback        | `after_save` et al.                        |
+| class_method    |                                            |
+| constant        |                                            |
+| constructor     |                                            |
+| enum            |                                            |
+| include         |                                            |
+| instance_method |                                            |
+| misc            | This is a configurable set of method calls |
+| module          | Any `module Foo; ...; end` declarations    |
+| scope           | Any `scope` or `default_scope` calls       |
+| validation      |                                            |
+
+
+Any model elements that are not included in "required order" will be ignored.
+
+Dark Finger ignores everything that appears after `private`. This may change in
+future, but for now we have just agreed that anything goes in the private
+section of our models.

data/lib/dark_finger.rb

@@ -2,3 +2,5 @@ require 'rubocop'
 require "dark_finger/version"
 require File.dirname(__FILE__) + "/rubocop/cop/dark_finger/model_structure"
 require File.dirname(__FILE__) + "/rubocop/cop/dark_finger/active_model_node_decorator"
+require File.dirname(__FILE__) + "/rubocop/cop/dark_finger/migration_constants"
+require File.dirname(__FILE__) + "/rubocop/cop/dark_finger/module_ancestor_chain_extractor"

data/lib/dark_finger/version.rb

@@ -1,3 +1,3 @@
 module DarkFinger
-  VERSION = "0.3.1"
+  VERSION = "0.6.1"
 end

data/lib/rubocop/cop/dark_finger/active_model_node_decorator.rb

@@ -1,3 +1,5 @@
+require 'delegate'
+
 module RuboCop
   module Cop
     module DarkFinger
@@ -60,6 +62,11 @@ module RuboCop
           end
         end
 
+        def private_declaration?
+          # need to check respond_to since this may not be called only "on_send"
+          respond_to?(:method_name) && method_name == :private && receiver.nil?
+        end
+
         private
 
         def nested_in_with_options?

data/lib/rubocop/cop/dark_finger/migration_constants.rb

@@ -0,0 +1,69 @@
+module RuboCop
+  module Cop
+    module DarkFinger
+      class MigrationConstants < ::RuboCop::Cop::Cop
+        DEFAULT_ALLOWED_CONSTANTS = [
+          'Migration',
+          'ActiveRecord',
+          'ActiveRecord::Migration',
+          'ActiveRecord::Base',
+          'ActiveRecord::IrreversibleMigration'
+        ]
+
+        attr_reader :allowed_constants
+
+        def initialize(*args, options)
+          super(*args)
+          @whitelisted_constants = options[:whitelisted_constants] || cop_config['whitelisted_constants'] || []
+          @allowed_constants =
+            DEFAULT_ALLOWED_CONSTANTS +
+            allowed_top_level_constants +
+            @whitelisted_constants
+        end
+
+        def on_const(node)
+          return if allowed_constants.include?(node.const_name)
+          add_offense(node, message: %Q(Undeclared constant: "#{node.const_name}"))
+        end
+
+        def on_casgn(node)
+          add_allowed_constant(node.children[1])
+        end
+
+        def on_class(node)
+          add_allowed_constant(node.children.first.const_name)
+          add_module_parent_chain_for(node)
+        end
+
+        def on_module(node)
+          add_allowed_constant(node.children.first.const_name)
+          add_module_parent_chain_for(node)
+        end
+
+        private
+
+        def allowed_top_level_constants
+          Module.constants.map(&:to_s) - top_level_model_classes_and_containing_modules
+        end
+
+        def top_level_model_classes_and_containing_modules
+          return [] unless Object.const_defined?('ActiveRecord::Base')
+
+          ::ActiveRecord::Base.descendants.map do |klass|
+            klass.name.sub(/::.*/, '').to_s
+          end.uniq
+        end
+
+        def add_allowed_constant(constant)
+          @allowed_constants << constant.to_s
+          @allowed_constants.uniq!
+        end
+
+        def add_module_parent_chain_for(node)
+          chain = ModuleAncestorChainExtractor.new(node).perform
+          add_allowed_constant(chain)
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/cop/dark_finger/model_structure.rb

@@ -68,12 +68,12 @@ module RuboCop
 
         attr_reader :required_order, :required_comments, :misc_method_names
 
-        def initialize(*args, required_order: nil, required_comments: nil, misc_method_names: nil, **_)
+        def initialize(*args, options)
           super
           @class_elements_seen = []
-          @required_order = required_order || cop_config['required_order'] || DEFAULT_REQUIRED_ORDER
-          @required_comments = required_comments || cop_config['required_comments'] || DEFAULT_REQUIRED_COMMENTS
-          @misc_method_names = misc_method_names || cop_config['misc_method_names'] || DEFAULT_MISC_METHOD_NAMES
+          @required_order = options[:required_order] || cop_config['required_order'] || DEFAULT_REQUIRED_ORDER
+          @required_comments = options[:required_comments] || cop_config['required_comments'] || DEFAULT_REQUIRED_COMMENTS
+          @misc_method_names = options[:misc_method_names] || cop_config['misc_method_names'] || DEFAULT_MISC_METHOD_NAMES
 
           # symbolize configs
           @required_order.map!(&:to_sym)
@@ -114,10 +114,16 @@ module RuboCop
 
         def process_node(node, seen_element: nil)
           return if @order_violation_reported
+          return if @seen_private_declaration
 
           node = ActiveModelNodeDecorator.new(node, misc_method_names: misc_method_names)
-          seen_element ||= node.node_type
 
+          if node.private_declaration?
+            @seen_private_declaration = true
+            return
+          end
+
+          seen_element ||= node.node_type
           return unless seen_element
 
           return if node.ignore_due_to_nesting?

data/lib/rubocop/cop/dark_finger/module_ancestor_chain_extractor.rb

@@ -0,0 +1,25 @@
+module RuboCop
+  module Cop
+    module DarkFinger
+      class ModuleAncestorChainExtractor
+        attr_reader :node
+
+        def initialize(node)
+          @node = node
+        end
+
+        def perform
+          module_chain = [node.children.first.const_name]
+
+          current_node = node
+          while current_node.parent && current_node.parent.module_type?
+            module_chain << current_node.parent.children.first.const_name
+            current_node = current_node.parent
+          end
+
+          module_chain.reverse.join("::")
+        end
+      end
+    end
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: dark_finger
 version: !ruby/object:Gem::Version
-  version: 0.3.1
+  version: 0.6.1
 platform: ruby
 authors:
 - Professor Wang Matrix PhD
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2018-10-06 00:00:00.000000000 Z
+date: 2020-07-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -89,6 +89,7 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".github/dark_finger.jpg"
 - ".gitignore"
 - ".rspec"
 - ".travis.yml"
@@ -99,10 +100,14 @@ files:
 - bin/console
 - bin/setup
 - dark_finger.gemspec
+- docs/migration_constants.md
+- docs/model_structure.md
 - lib/dark_finger.rb
 - lib/dark_finger/version.rb
 - lib/rubocop/cop/dark_finger/active_model_node_decorator.rb
+- lib/rubocop/cop/dark_finger/migration_constants.rb
 - lib/rubocop/cop/dark_finger/model_structure.rb
+- lib/rubocop/cop/dark_finger/module_ancestor_chain_extractor.rb
 homepage: https://github.com/the-suBLAM-executive-council/dark_finger
 licenses:
 - MIT
@@ -122,8 +127,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubyforge_project: 
-rubygems_version: 2.5.2.1
+rubygems_version: 3.1.2
 signing_key: 
 specification_version: 4
 summary: ActiveModel layout cop for Rubocop