rails_best_practices 0.5.6 → 0.6.1

data/lib/rails_best_practices/checks/use_model_association_check.rb

@@ -3,19 +3,42 @@ require 'rails_best_practices/checks/check'
 
 module RailsBestPractices
   module Checks
-    # Check a model creation to make sure using model association.
+    # Check a controller file to make sure to use model association instead of foreign key id assignment.
     #
-    # Implementation: 
-    # 1. check :attrasgn, if xxx_id is assigned to a variable, set the value of the assigned variable to true.
-    # 2. check :call, if call message :save and caller is included in variables, add error.
+    # See the best practice details here http://rails-bestpractices.com/posts/2-use-model-association.
+    #
+    # Implementation:
+    #
+    # Prepare process:
+    #   none
+    #
+    # Review process:
+    #   check model define nodes in all controller files,
+    #   if there is an attribute assignment node with message xxx_id=,
+    #   and after it, there is a call node with message :save or :save!,
+    #   and the subjects of attribute assignment node and call node are the same,
+    #   then model association should be used instead of xxx_id assignment.
     class UseModelAssociationCheck < Check
-      
-      def interesting_nodes
+
+      def interesting_review_nodes
         [:defn]
       end
 
-      def evaluate_start(node)
-        @variables = {}
+      def interesting_review_files
+        CONTROLLER_FILES
+      end
+
+      # check method define nodes to see if there are some attribute assignments that can use model association instead in review process.
+      #
+      # it will check attribute assignment node with message xxx_id=, and call node with message :save or :save!
+      #
+      # 1. if there is an attribute assignment node with message xxx_id=,
+      #    then remember the subject of attribute assignment node.
+      # 2. after assignment, if there is a call node with message :save or :save!,
+      #    and the subject of call node is one of the subject of attribute assignment node,
+      #    then the attribute assignment should be replaced by using model association.
+      def review_start_defn(node)
+        @attrasgns = {}
         node.recursive_children do |child|
           case child.node_type
           when :attrasgn
@@ -25,24 +48,40 @@ module RailsBestPractices
           else
           end
         end
-        @variables = nil
+        @attrasgns = nil
       end
-      
+
       private
-      
-      def attribute_assignment(node)
-        if node.message.to_s =~ /_id=$/
-          variable = node.subject[1]
-          @variables[variable] = true
+        # check an attribute assignment node, if its message is xxx_id, like
+        #
+        #     s(:attrasgn, s(:ivar, :@post), :user_id=,
+        #       s(:arglist,
+        #         s(:call, s(:call, nil, :current_user, s(:arglist)), :id, s(:arglist))
+        #       )
+        #     )
+        #
+        # then remember the subject of the attribute assignment in @attrasgns.
+        #
+        #     @attrasgns => { s(:ivar, :@post) => true }
+        def attribute_assignment(node)
+          if node.message.to_s =~ /_id=$/
+            subject = node.subject
+            @attrasgns[subject] = true
+          end
         end
-      end
-      
-      def call_assignment(node)
-        if node.message == :save
-          variable = node.subject[1]
-          add_error "use model association (for #{node.subject})" if @variables[variable]
+
+        # check a call node with message :save or :save!,
+        # if the subject of call node exists in @attrasgns, like
+        #
+        #     s(:call, s(:ivar, :@post), :save, s(:arglist))
+        #
+        # then the attribute assignment should be replaced by using model association.
+        def call_assignment(node)
+          if [:save, :save!].include? node.message
+            subject = node.subject
+            add_error "use model association (for #{subject})" if @attrasgns[subject]
+          end
         end
-      end
     end
   end
 end

data/lib/rails_best_practices/checks/use_observer_check.rb

@@ -3,51 +3,153 @@ require 'rails_best_practices/checks/check'
 
 module RailsBestPractices
   module Checks
-    # Check a model file to make sure mail deliver method is in observer not callback.
+    # Make sure to use observer (sorry we only check the mailer deliver now).
     #
-    # Implementation: 
-    # Record :after_create callback
-    # Check method define, if it is a callback and call deliver_xxx message in method body, then it should use observer.
+    # See the best practice details here http://rails-bestpractices.com/posts/19-use-observer.
+    #
+    # TODO: we need a better solution, any suggestion?
+    #
+    # Implementation:
+    #
+    # Prepare process:
+    #   check all class nodes to see if they are the subclass of ActionMailer::Base,
+    #   if so, remember the class name.
+    #
+    # Review process:
+    #   check all call nodes to see if they are callback definitions, like after_create, before_destroy,
+    #   if so, remember the callback methods.
+    #
+    #   check all method define nodes to see
+    #   if the method is a callback method,
+    #   and there is a mailer deliver call,
+    #   then the method should be replaced by using observer.
     class UseObserverCheck < Check
 
-      def interesting_nodes
+      def interesting_prepare_nodes
+        [:class]
+      end
+
+      def interesting_review_nodes
         [:defn, :call]
       end
 
-      def interesting_files
-        MODLE_FILES
+      def interesting_prepare_files
+        /#{MAILER_FILES}|#{MODEL_FILES}/
+      end
+
+      def interesting_review_files
+        MODEL_FILES
       end
 
       def initialize
         super
         @callbacks = []
+        @mailer_names = []
+      end
+
+      # check class node in prepare process.
+      #
+      # if it is a subclass of ActionMailer::Base,
+      # then remember its class name.
+      def prepare_start_class(node)
+        remember_mailer_names(node)
+      end
+
+      # check a call node in review process.
+      #
+      # if it is a callback definition, like
+      #
+      #     after_create :send_create_notification
+      #     before_destroy :send_destroy_notification
+      #
+      # then remember its callback methods (:send_create_notification).
+      def review_start_call(node)
+        remember_callback(node)
       end
 
-      def evaluate_start(node)
-        if :after_create == node.message
-          remember_callbacks(node)
-        elsif :defn == node.node_type and @callbacks.find { |callback| equal?(callback, node.message_name) }
-          add_error "use observer" if use_observer?(node)
+      # check a method define node in prepare process.
+      #
+      # if it is callback method,
+      # and there is a actionmailer deliver call in the method define node,
+      # then it should be replaced by using observer.
+      def review_start_defn(node)
+        if callback_method?(node) and deliver_mailer?(node)
+          add_error "use observer"
         end
       end
 
       private
+        # check a class node, if its base class is ActionMailer::Base, like
+        #
+        #     s(:class, :ProjectMailer,
+        #       s(:colon2, s(:const, :ActionMailer), :Base),
+        #       s(:scope)
+        #     )
+        #
+        # then save the class name in @mailer_names
+        def remember_mailer_names(node)
+          if s(:colon2, s(:const, :ActionMailer), :Base) == node.base_class
+            @mailer_names << node.class_name.to_s
+          end
+        end
 
-      def remember_callbacks(node)
-        node.arguments[1..-1].each do |argument|
-          # ignore callback like after_create Comment.new
-          if :lit == argument.node_type
-            @callbacks << argument.to_s
+        # check a call node, if it is a callback definition, such as after_create, before_create, like
+        #
+        #     s(:call, nil, :after_create,
+        #       s(:arglist, s(:lit, :send_create_notification))
+        #     )
+        #
+        # then save the callback methods in @callbacks
+        #
+        #     @callbacks => [:send_create_notification]
+        def remember_callback(node)
+          if node.message.to_s =~ /^after_|^before_/
+            node.arguments[1..-1].each do |argument|
+              # ignore callback like after_create Comment.new
+              @callbacks << argument.to_s if :lit == argument.node_type
+            end
           end
         end
-      end
 
-      def use_observer?(node)
-        node.recursive_children do |child|
-          return true if :call == child.node_type and :const == child.subject.node_type and child.message.to_s =~ /^deliver_/
+        # check a defn node to see if the method name exists in the @callbacks.
+        def callback_method?(node)
+          @callbacks.find { |callback| equal?(callback, node.method_name) }
+        end
+
+        # check a defn node to see if it contains a actionmailer deliver call.
+        #
+        # for rails2
+        #
+        # if the message of call node is deliver_xxx,
+        # and the subject of the call node exists in @callbacks, like
+        #
+        #     s(:call, s(:const, :ProjectMailer), :deliver_notification,
+        #       s(:arglist, s(:self), s(:lvar, :member))
+        #     )
+        #
+        # for rails3
+        #
+        # if the message of call node is deliver,
+        # and the subject of the call node is with subject node who exists in @callbacks, like
+        #
+        #     s(:call,
+        #       s(:call, s(:const, :ProjectMailer), :notification,
+        #         s(:arglist, s(:self), s(:lvar, :member))
+        #       ),
+        #       :deliver,
+        #       s(:arglist)
+        #     )
+        #
+        # then the call node is actionmailer deliver call.
+        def deliver_mailer?(node)
+          node.grep_nodes(:node_type => :call) do |child_node|
+            # rails2 actionmailer deliver
+            return true if child_node.message.to_s =~ /^deliver_/ && @mailer_names.include?(child_node.subject.to_s)
+            # rails3 actionmailer deliver
+            return true if :deliver == child_node.message && @mailer_names.include?(child_node.subject.subject.to_s)
+          end
+          false
         end
-        false
-      end
     end
   end
 end

data/lib/rails_best_practices/checks/use_query_attribute_check.rb

@@ -3,43 +3,46 @@ require 'rails_best_practices/checks/check'
 
 module RailsBestPractices
   module Checks
-    # Check to make sure use query attribute instead of nil?, blank? and present?.
+    # Make sure to use query attribute instead of nil?, blank? and present?.
+    #
+    # See the best practice details here http://rails-bestpractices.com/posts/56-use-query-attribute.
     #
     # Implementation:
-    # 1. check all models to save model names and association names.
-    #    model names are used for detecting
-    #    association name should not be detected as query attribute
-    # 2. check all method calls, if their subjects are model names and their messages are one of nil?,
-    #    blank?, present? or == "", not pluralize and not in the association names,
-    #    then they need to use query attribute.
+    #
+    # Prepare process:
+    #   only check all model files to save model names and association names,
+    #   model names are saved as only when subject of call method is equal to one of the model name, then the call method may use query attribute instead,
+    #   association names are saved as association attributes should not be detected as query attributes.
+    #
+    # Review process:
+    #   check all method calls within conditional statements, like @user.login.nil?
+    #   if their subjects are one of the model names
+    #   and their messages of first call are not pluralize and not in any of the association names
+    #   and their messages of second call are one of nil?, blank?, present?, or they are == ""
+    #   then you can use query attribute instead.
     class UseQueryAttributeCheck < Check
 
       QUERY_METHODS = [:nil?, :blank?, :present?]
-      ASSOCIATION_METHODS = [:belongs_to, :has_one, :has_many, :has_and_belongs_to_many]
 
-      def interesting_nodes
-        [:if, :class, :call]
-      end
-
-      def interesting_prepare_files
-        MODLE_FILES
-      end
+      prepare_model_associations
 
-      def initialize
-        super
-        @klazzes = []
-        @associations = {}
+      def interesting_review_nodes
+        [:if]
       end
 
-      def prepare_start_class(node)
-        remember_klazz(node)
-      end
-
-      def prepare_start_call(node)
-        remember_association(node) if ASSOCIATION_METHODS.include? node.message
-      end
-
-      def evaluate_start_if(node)
+      # check if node to see whose conditional statement nodes contain nodes that can use query attribute instead in review process.
+      #
+      # it will check every call nodes in the if nodes. If the call node is
+      #
+      # 1. two method calls, like @user.login.nil?
+      # 2. the subject is one of the model names
+      # 3. the message of first call is the model's attribute,
+      #    the message is not in any of associations name and is not pluralize
+      # 4. the message of second call is one of nil?, blank? or present? or
+      #    the message is == and the argument is ""
+      #
+      # then the call node can use query attribute instead.
+      def review_start_if(node)
         if node = query_attribute_node(node.conditional_statement)
           subject_node = node.subject
           add_error "use query attribute (#{subject_node.subject}.#{subject_node.message}?)", node.file, node.line
@@ -47,17 +50,7 @@ module RailsBestPractices
       end
 
       private
-        def remember_klazz(class_node)
-          if class_node.file =~ MODLE_FILES
-            @klazzes << class_node.subject
-          end
-        end
-
-        def remember_association(association_node)
-          @associations[@klazzes.last] ||= []
-          @associations[@klazzes.last] << association_node.arguments[1].to_s
-        end
-
+        # recursively check conditional statement nodes to see if there is a call node that may be possible query attribute.
         def query_attribute_node(conditional_statement_node)
           case conditional_statement_node.node_type
           when :and, :or
@@ -65,25 +58,60 @@ module RailsBestPractices
           when :not
             return query_attribute_node(conditional_statement_node[1])
           when :call
-            return conditional_statement_node if query_method?(conditional_statement_node) or compare_with_empty_string?(conditional_statement_node)
+            return conditional_statement_node if possible_query_attribute?(conditional_statement_node)
           end
           nil
         end
 
-        def query_method?(node)
+        # check if the node may use query attribute instead.
+        #
+        # if the node contains two method calls, e.g. @user.login.nil?
+        #
+        # for the first call, the subject should be one of the class names and
+        # the message should not be one of the association name and the message should not be pluralize.
+        #
+        # for the second call, the message should be one of nil?, blank? or present? or
+        # it is compared with an empty string.
+        #
+        # the node that may use query attribute is like
+        #
+        #     s(:call, s(:call, s(:ivar, :@user), :login, s(:arglist)), :nil?, s(:arglist))
+        #
+        #
+        def possible_query_attribute?(node)
           return false unless :call == node.subject.node_type
           subject = node.subject.subject
           message = node.subject.message
-          subject_ruby = subject.to_s
 
-          subject_ruby && node.subject.arguments.size == 1 &&
-            @klazzes.find { |klazz| subject_ruby =~ %r|#{klazz.to_s.underscore}| and !@associations[klazz].find { |association| equal?(association, message) } } &&
-            message && message.to_s.pluralize != message.to_s &&
-          QUERY_METHODS.include?(node.message)
+          [:arglist] == node.subject.arguments && class_attribute?(subject, message) && !pluralize?(message.to_s) &&
+            (QUERY_METHODS.include?(node.message) || compare_with_empty_string?(node))
+        end
+
+        # check if the subject and message is one of the model's attribute.
+        # the subject should match one of the class model name, and the message should not match any of association name.
+        #
+        #     subject, subject of call node, like
+        #         s(:ivar, @user)
+        #
+        #     message, message of call node, like
+        #         :login
+        def class_attribute?(subject, message)
+          @klazzes.find do |klazz|
+            subject.to_s =~ %r|#{klazz.to_s.underscore}| && !@associations[klazz].find { |association| equal?(association, message) }
+          end
+        end
+
+
+        # check if the str is a pluralize string.
+        def pluralize?(str)
+          str.pluralize == str
         end
 
+        # check if the node is with node type :call, node message :== and node arguments {:arglist, (:str, "")}
+        #
+        #     @user.login == "" => true
         def compare_with_empty_string?(node)
-          :== == node.message and [:arglist, [:str, ""]] == node.arguments
+          :call == node.node_type && :== == node.message && [:arglist, [:str, ""]] == node.arguments
         end
     end
   end

data/lib/rails_best_practices/checks/use_say_with_time_in_migrations_check.rb

@@ -3,26 +3,75 @@ require 'rails_best_practices/checks/check'
 
 module RailsBestPractices
   module Checks
-    # Check a migration file to make sure to use say_with_time for customized data changes to produce a more readable output.
+    # Check a migration file to make sure to use say or say_with_time for customized data changes to produce a more readable output.
     #
-    # Implementation: check if there are any first level messages called in self.up and self.down except say_with_time and default migration messages (such as :add_column and :create_table)
+    # See the best practice detials here http://rails-bestpractices.com/posts/46-use-say-and-say_with_time-in-migrations-to-make-a-useful-migration-log.
+    #
+    # Implementation:
+    #
+    # Prepare process:
+    #   none
+    #
+    # Review process:
+    #   check class method define nodes (self.up or self.down).
+    #   if there is a method call in the class method definition,
+    #   and the message of method call is not say, say_with_time and default migration methods (such as add_column and create_table),
+    #   then the method call should be wrapped by say or say_with_time.
     class UseSayWithTimeInMigrationsCheck < Check
 
-      DEFAULT_MIGRATION_MESSAGES = [:add_column, :add_index, :add_timestamps, :change_column, :change_column_default, :change_table, :create_table, :drop_table, :remove_column, :remove_index, :remove_timestamps, :rename_column, :rename_index, :rename_table]
+      DEFAULT_MIGRATION_METHODS = [:add_column, :add_index, :add_timestamps, :change_column, :change_column_default, :change_table, :create_table, :drop_table, :remove_column, :remove_index, :remove_timestamps, :rename_column, :rename_index, :rename_table]
+      WITH_SAY_METHODS = DEFAULT_MIGRATION_METHODS + [:say, :say_with_time]
+
 
-      def interesting_nodes
+      def interesting_review_nodes
         [:defs]
       end
 
-      def interesting_files
+      def interesting_review_files
         MIGRATION_FILES
       end
 
-      def evaluate_start(node)
-        block_body = node.grep_nodes(:node_type => :block).first.body
-        block_body.each do |iter|
-          if :iter == iter.node_type and :call == iter[1].node_type and !(DEFAULT_MIGRATION_MESSAGES << :say_with_time).include? iter[1].message
-            add_error("use say with time in migrations", iter[1].file, iter[1].line)
+      # check a class method define node to see if there are method calls that need to be wrapped by :say or :say_with_time in review process.
+      #
+      # it will check the first block node,
+      # if any method call whose message is not default migration methods in the block node, like
+      #
+      #     s(:defs, s(:self), :up, s(:args),
+      #       s(:scope,
+      #         s(:block,
+      #           s(:iter,
+      #             s(:call, s(:const, :User), :find_each, s(:arglist)),
+      #             s(:lasgn, :user),
+      #             s(:block,
+      #               s(:masgn,
+      #                 s(:array,
+      #                   s(:attrasgn, s(:lvar, :user), :first_name=, s(:arglist)),
+      #                   s(:attrasgn, s(:lvar, :user), :last_name=, s(:arglist))
+      #                 ),
+      #                 s(:to_ary,
+      #                   s(:call,
+      #                     s(:call, s(:lvar, :user), :full_name, s(:arglist)),
+      #                     :split,
+      #                     s(:arglist, s(:str, " "))
+      #                   )
+      #                 )
+      #               ),
+      #               s(:call, s(:lvar, :user), :save, s(:arglist))
+      #             )
+      #           )
+      #         )
+      #       )
+      #     )
+      #
+      # then such method call should be wrapped by say or say_with_time
+      def review_start_defs(node)
+        block_node = node.grep_node(:node_type => :block)
+        block_node.children.each do |child_node|
+          if :iter == child_node.node_type
+            subject_node = child_node.subject
+            if :call == subject_node.node_type && !WITH_SAY_METHODS.include?(subject_node.message)
+              add_error("use say with time in migrations", subject_node.file, subject_node.line)
+            end
           end
         end
       end