rails_best_practices 0.5.6 → 0.6.1

data/lib/rails_best_practices/checks/always_add_db_index_check.rb

@@ -5,14 +5,34 @@ module RailsBestPractices
   module Checks
     # Check db/schema.rb file to make sure every reference key has a database index.
     #
-    # Implementation: read all add_index method calls to get the indexed columns in table, then read integer method call in create_table block to get the reference columns in tables (or polymorphic index like [commentable_id, commentable_type]), compare with indexed columns, if not in the indexed columns, then it violates always_add_db_index_check.
+    # See the best practice details here http://rails-bestpractices.com/posts/21-always-add-db-index
+    #
+    # Implementation:
+    #
+    # Prepare process:
+    #   none
+    #
+    # Review process:
+    #   only check the call nodes and at the end of iter node in db/schema file,
+    #   if the subject of call node is :create_table, then remember the table names
+    #   if the subject of call node is :integer, then remember it as foreign key
+    #   if the sujbect of call node is :string, the name of it is _type suffixed and there is an integer column _id suffixed, then remember it as polymorphic foreign key
+    #   if the subject of call node is :add_index, then remember the index columns
+    #   after all of these, at the end of iter node
+    #
+    #       ActiveRecord::Schema.define(:version => 20101201111111) do
+    #         ......
+    #       end
+    #
+    #   if there are any foreign keys not existed in index columns,
+    #   then the foreign keys should add db index.
     class AlwaysAddDbIndexCheck < Check
 
-      def interesting_nodes
-        [:block, :call, :iter]
+      def interesting_review_nodes
+        [:call, :iter]
       end
 
-      def interesting_files
+      def interesting_review_files
         /db\/schema.rb/
       end
 
@@ -23,23 +43,76 @@ module RailsBestPractices
         @table_nodes = {}
       end
 
-      def evaluate_start(node)
-        if :block == node.node_type
-          find_index_columns(node)
-        elsif :call == node.node_type
-          case node.message
-          when :create_table
-            @table_name = node.arguments[1].to_s
-            @table_nodes[@table_name] = node
-          when :integer, :string
-            column_name = node.arguments[1].to_s
-            add_foreign_key_column(@table_name, column_name)
-          end
+      # check call node in review process.
+      #
+      # if the message of call node is :create_table,
+      # then remember the table name (@table_nodes) like
+      #     {
+      #       "comments" =>
+      #         s(:call, nil, :create_table, s(:arglist, s(:str, "comments"), s(:hash, s(:lit, :force), s(:true))))
+      #     }
+      #
+      # if the message of call node is :integer,
+      # then remember it as a foreign key of last create table name.
+      #
+      # if the message of call node is :type and the name of argument is _type suffixed,
+      # then remember it with _id suffixed column as polymorphic foreign key.
+      #
+      # the remember foreign keys (@foreign_keys) like
+      #
+      #   {
+      #     "taggings" =>
+      #       ["tag_id", ["taggable_id", "taggable_type"]]
+      #   }
+      #
+      # if the message of call node is :add_index,
+      # then remember it as index columns (@index_columns) like
+      #
+      #   {
+      #     "comments" =>
+      #       ["post_id", "user_id"]
+      #   }
+      def review_start_call(node)
+        case node.message
+        when :create_table
+          remember_table_nodes(node)
+        when :integer, :string
+          remember_foreign_key_columns(node)
+        when :add_index
+          remember_index_columns(node)
+        else
         end
       end
 
-      def evaluate_end(node)
-        if :iter == node.node_type && :call == node.subject.node_type && s(:colon2, s(:const, :ActiveRecord), :Schema) == node.subject.subject
+      # check at the end of iter node, like
+      #
+      #     s(:iter,
+      #       s(:call,
+      #         s(:colon2, s(:const, :ActiveRecord), :Schema),
+      #         :define,
+      #         s(:arglist, s(:hash, s(:lit, :version), s(:lit, 20100603080629)))
+      #       ),
+      #       nil,
+      #       s(:iter,
+      #         s(:call, nil, :create_table,
+      #           s(:arglist, s(:str, "comments"), s(:hash, s(:lit, :force), s(:true)))
+      #         ),
+      #         s(:lasgn, :t),
+      #         s(:block,
+      #           s(:call, s(:lvar, :t), :string, s(:arglist, s(:str, "content")))
+      #         )
+      #       )
+      #     )
+      #
+      # if the subject of iter node is with subject ActiveRecord::Schema,
+      # it means we have completed the foreign keys and index columns parsing,
+      # then we compare foreign keys and index columns.
+      #
+      # if there are any foreign keys not existed in index columns,
+      # then we should add db index for that foreign keys.
+      def review_end_iter(node)
+        first_node = node.subject
+        if :call == first_node.node_type && s(:colon2, s(:const, :ActiveRecord), :Schema) == first_node.subject
           remove_only_type_foreign_keys
           @foreign_keys.each do |table, foreign_key|
             table_node = @table_nodes[table]
@@ -53,20 +126,63 @@ module RailsBestPractices
       end
 
       private
-        def find_index_columns(node)
-          node.grep_nodes({:node_type => :call, :message => :add_index}).each do |index_node|
-            table_name = index_node.arguments[1].to_s
-            index_column = eval(index_node.arguments[2].to_s)
-            add_index_column(table_name, index_column)
-          end
-        end
+        # remember the node as index columns
+        #
+        #     s(:call, nil, :add_index,
+        #       s(:arglist,
+        #         s(:str, "comments"),
+        #         s(:array, s(:str, "post_id")),
+        #         s(:hash, s(:lit, :name), s(:str, "index_comments_on_post_id"))
+        #       )
+        #     )
+        #
+        # the remember index columns are like
+        #     {
+        #       "comments" =>
+        #         ["post_id", "user_id"]
+        #     }
+        def remember_index_columns(node)
+          table_name = node.arguments[1].to_s
+          index_column = eval(node.arguments[2].to_s)
 
-        def add_index_column(table_name, index_column)
           @index_columns[table_name] ||= []
           @index_columns[table_name] << (index_column.size == 1 ? index_column[0] : index_column)
         end
 
-        def add_foreign_key_column(table_name, foreign_key_column)
+        # remember table nodes
+        #
+        # if the node is
+        #
+        #     s(:call, nil, :create_table,
+        #       s(:arglist, s(:str, "comments"), s(:hash, s(:lit, :force), s(:true))))
+        #
+        # then the table nodes will be
+        #
+        #     {
+        #       "comments" =>
+        #         s(:call, nil, :create_table, s(:arglist, s(:str, "comments"), s(:hash, s(:lit, :force), s(:true))))
+        #     }
+        def remember_table_nodes(node)
+          @table_name = node.arguments[1].to_s
+          @table_nodes[@table_name] = node
+        end
+
+
+        # remember foreign key columns
+        #
+        # if the message of node is :integer,
+        # then it is a foreign key, like
+        #
+        #     s(:call, s(:lvar, :t), :integer, s(:arglist, s(:str, "post_id")))
+        #
+        # if the message of node is :string, with _type suffixed and there is a _id suffixed column,
+        # then they are polymorphic foreign key
+        #
+        #     s(:call, s(:lvar, :t), :integer, s(:arglist, s(:str, "taggable_id")))
+        #     s(:call, s(:lvar, :t), :string, s(:arglist, s(:str, "taggable_type")))
+        def remember_foreign_key_columns(node)
+          table_name = @table_name
+          foreign_key_column = node.arguments[1].to_s
           @foreign_keys[table_name] ||= []
           if foreign_key_column =~ /(.*?)_id$/
             if @foreign_keys[table_name].delete("#{$1}_type")
@@ -83,18 +199,21 @@ module RailsBestPractices
           end
         end
 
+        # remove the non foreign keys with only _type column.
         def remove_only_type_foreign_keys
           @foreign_keys.delete_if { |table, foreign_key|
             foreign_key.size == 1 && foreign_key[0] =~ /_type$/
           }
         end
 
+        # check if the table's column is indexed.
         def indexed?(table, column)
           index_columns = @index_columns[table]
-          !index_columns || !index_columns.any? { |e| greater_than(Array(e), Array(column)) }
+          !index_columns || !index_columns.any? { |e| greater_than_or_equal(Array(e), Array(column)) }
         end
 
-        def greater_than(more_array, less_array)
+        # check if more_array is greater than less_array or equal to less_array.
+        def greater_than_or_equal(more_array, less_array)
           more_size = more_array.size
           less_size = less_array.size
           (more_array - less_array).size == more_size - less_size

data/lib/rails_best_practices/checks/check.rb

@@ -3,14 +3,21 @@ require 'rails_best_practices/core/error'
 
 module RailsBestPractices
   module Checks
+    # A Check class that takes charge of reviewing one rails best practice.
+    # One check contains two process:
+    # 1. prepare process (optional), in this process, one check will do some preparation, such as analyzing the model associations.The check only does the preparation for the nodes (defined in interesting_prepare_nodes) in the files (defined in interesting_prepare_files).
+    # 2. review process, in this process, one check will really review your rails codes. The check only review the nodes (defined in interesting_review_nodes) in the files # (defined in interesting_review_files).
     class Check
-      NODE_TYPES = [:call, :defn, :defs, :if, :unless, :class, :lasgn, :iasgn, :ivar, :lvar, :block, :iter, :const]
+      # only nodes whose node_type is in NODE_TYPE will be reviewed.
+      NODE_TYPES = [:call, :defn, :defs, :if, :class, :lasgn, :iasgn, :ivar, :lvar, :block, :iter, :const]
 
       CONTROLLER_FILES = /_controller\.rb$/
       MIGRATION_FILES = /db\/migrate\/.*\.rb$/
-      MODLE_FILES = /models\/.*\.rb$/
+      MODEL_FILES = /models\/.*\.rb$/
+      MAILER_FILES = /models\/.*\.rb$|mailers\/.*\.rb/
       VIEW_FILES = /views\/.*\.(erb|haml)$/
       PARTIAL_VIEW_FILES = /views\/.*\/_.*\.(erb|haml)$/
+      ROUTE_FILE = /config\/routes.rb/
 
       attr_reader :errors
 
@@ -18,82 +25,178 @@ module RailsBestPractices
         @errors = []
       end
 
-      def interesting_files
-        /.*/
-      end
-
-      def interesting_prepare_files
-        /.*/
-      end
-
-      NODE_TYPES.each do |node|
-        start_node_method = "evaluate_start_#{node}"
-        end_node_method = "evaluate_end_#{node}"
-        define_method(start_node_method) { |node| } unless self.respond_to?(start_node_method)
-        define_method(end_node_method) { |node| } unless self.respond_to?(end_node_method)
-
-        prepare_start_node_method = "prepare_start_#{node}"
-        prepare_end_node_method = "prepare_end_#{node}"
-        define_method(prepare_start_node_method) { |node| } unless self.respond_to?(prepare_start_node_method)
-        define_method(prepare_end_node_method) { |node| } unless self.respond_to?(prepare_end_node_method)
-      end
-
-      def position(offset = 0)
-        "#{@line[2]}:#{@line[1] + offset}"
-      end
-
-      def prepare_start(node)
-      end
-
-      def prepare_end(node)
-      end
-
-      def evaluate_start(node)
-      end
-
-      def evaluate_end(node)
-      end
-
-      def prepare_node(position, node)
-        @node = node
-        prepare_method = "prepare_#{position}_#{node.node_type}"
-        self.send(prepare_method, node)
-      end
-
-      def evaluate_node(position, node)
-        @node = node
-        eval_method = "evaluate_#{position}_#{node.node_type}"
-        self.send(eval_method, node)
-      end
-
-      def prepare_node_start(node)
-        prepare_node(:start, node)
-        prepare_start(node)
-      end
-
-      def prepare_node_end(node)
-        prepare_node(:end, node)
-        prepare_end(node)
-      end
-
-      def evaluate_node_start(node)
-        evaluate_node(:start, node)
-        evaluate_start(node)
-      end
-
-      def evaluate_node_end(node)
-        evaluate_node(:end, node)
-        evaluate_end(node)
-      end
-
-      def add_error(error, file = nil, line = nil)
-        file ||= @node.file
-        line ||= @node.line
+      # define default interesting_prepare_nodes, interesting_review_nodes, interesting_prepare_files and interesting_review_files.
+      [:prepare, :review].each do |process|
+        class_eval <<-EOS
+          def interesting_#{process}_nodes                        # def interesting_review_nodes
+            []                                                    #   []
+          end                                                     # end
+                                                                  #
+          def interesting_#{process}_files                        # def interesting_review_files
+            /.*/                                                  #   /.*/
+          end                                                     # end
+        EOS
+      end
+
+      # define method prepare_node_start, prepare_node_end, review_node_start and review_node_end.
+      #
+      # they delegate the node to special process method, like
+      #
+      #     review_node_start(call_node) => review_start_call(call_node)
+      #     review_node_end(defn_node) => review_end_defn(defn_node)
+      #     prepare_node_start(calss_node) => prepare_start_class(class_node)
+      #     prepare_node_end(if_node) => prepare_end_if(if_node)
+      [:prepare, :review].each do |process|
+        class_eval <<-EOS
+          def #{process}_node_start(node)                         # def review_node_start(node)
+            @node = node                                          #   @node = node
+            method = "#{process}_start_" + node.node_type.to_s    #   method = "review_start_" + node.node_type.to_s
+            self.send(method, node)                               #   self.send(method, node)
+          end                                                     # end
+                                                                  #
+          def #{process}_node_end(node)                           # def review_node_end(node)
+            @node = node                                          #   @node = node
+            method = "#{process}_end_" + node.node_type.to_s      #   method = "review_end_" + node.node_type.to_s
+            self.send(method, node)                               #   self.send(method, node)
+          end                                                     # end
+        EOS
+      end
+
+      # define all start and end process for each node type, like
+      #
+      #     prepare_start_defn
+      #     prepare_end_defn
+      #     review_start_call
+      #     review_end_call
+      [:prepare, :review].each do |process|
+        NODE_TYPES.each do |node|
+          class_eval <<-EOS
+            def #{process}_start_#{node}(node)                    # def review_start_defn(node)
+            end                                                   # end
+                                                                  #
+            def #{process}_end_#{node}(node)                      # def review_end_defn(node)
+            end                                                   # end
+          EOS
+        end
+      end
+
+      # remember the model names and model associations in prepare process.
+      def self.prepare_model_associations
+        class_eval <<-EOS
+          def initialize
+            super
+            @klazzes = []
+            @associations = {}
+          end
+
+          def interesting_prepare_nodes
+            [:class, :call]
+          end
+
+          def interesting_prepare_files
+            MODEL_FILES
+          end
+
+          # check class node to remember all class name in prepare process.
+          #
+          # the remembered class names (@klazzes) are like
+          #     [ :User, :Post ]
+          def prepare_start_class(node)
+            remember_klazz(node)
+          end
+
+          # check call node to remember all assoication names in prepare process.
+          #
+          # the remembered association names (@associations) are like
+          #     { :User => [":projects", ":location"], :Post => [":comments"] }
+          def prepare_start_call(node)
+            remember_association(node) if association_methods.include? node.message
+          end
+
+          # remember class models, just the subject of class node.
+          def remember_klazz(class_node)
+            @klazzes << class_node.class_name
+          end
+
+          # remember associations, with class to association names.
+          def remember_association(association_node)
+            @associations[@klazzes.last] ||= []
+            @associations[@klazzes.last] << association_node.arguments[1].to_s
+          end
+
+          # default rails association methods.
+          def association_methods
+            [:belongs_to, :has_one, :has_many, :has_and_belongs_to_many]
+          end
+
+        EOS
+      end
+
+      # add error if source code violates rails best practice.
+      #   error is the string message for violation of the rails best practice
+      #   file is the filename of source code
+      #   line is the line number of the source code which is reviewing
+      def add_error(error, file = @node.file, line = @node.line)
         @errors << RailsBestPractices::Core::Error.new("#{file}", "#{line}", error)
       end
 
-      def equal?(node, expected)
-        node.to_s == expected or node.to_s == ':' + expected.to_s
+      # remember use count for the local or instance variable in the call or attrasgn node.
+      #
+      # find the local variable or instance variable in the call or attrasgn node,
+      # then save it to as key in @variable_use_count hash, and add the call count (hash value).
+      def remember_variable_use_count(node)
+        variable_node = variable(node)
+        if variable_node
+          variable_use_count[variable_node] ||= 0
+          variable_use_count[variable_node] += 1
+        end
+      end
+
+      # return @variable_use_count hash.
+      def variable_use_count
+        @variable_use_count ||= {}
+      end
+
+      # reset @variable_use_count hash.
+      def reset_variable_use_count
+        @variable_use_count = nil
+      end
+
+      # find local variable or instance variable in the most inner call node, e.g.
+      #
+      # if the call node is
+      #
+      #     s(:call, s(:ivar, :@post), :editors, s(:arglist)),
+      #
+      # or it is
+      #
+      #     s(:call,
+      #       s(:call, s(:ivar, :@post), :editors, s(:arglist)),
+      #       :include?,
+      #       s(:arglist, s(:call, nil, :current_user, s(:arglist)))
+      #     )
+      #
+      # then the variable both are s(:ivar, :@post).
+      #
+      def variable(node)
+        while node.subject.node_type == :call
+          node = node.subject
+        end
+        subject_node = node.subject
+        if [:ivar, :lvar].include?(subject_node.node_type) and subject_node[1] != :_erbout
+          subject_node
+        else
+          nil
+        end
+      end
+
+      # compare two sexp nodes' to_s.
+      #     equal?(":test", :test) => true
+      #     equai?("@test", :test) => true
+      def equal?(node, expected_node)
+        actual = node.to_s.downcase
+        expected = expected_node.to_s.downcase
+        actual == expected || actual == ':' + expected || actual == '@' + expected
       end
     end
   end