rails_best_practices 0.5.6 → 0.6.1

data/README.md

@@ -0,0 +1,161 @@
+rails_best_practices
+====================
+
+rails_best_practices is a code metric tool to check the quality of rails codes.
+
+Donate
+------
+
+<a href='http://www.pledgie.com/campaigns/12057'><img alt='Click here to lend your support to: rails-bestpractices.com and make a donation at www.pledgie.com !' src='http://www.pledgie.com/campaigns/12057.png?skin_name=chrome' border='0' /></a>
+
+Usage
+-----
+
+At the root directory of rails app
+
+    rails_best_practices .
+
+By default rails_best_practices will do parse codes in vendor, spec, test and features directories. If you need, see the command options:
+
+    $ rails_best_practices -h
+    Usage: rails_best_practices [options]
+        -d, --debug                      Debug mode
+            --vendor                     include vendor files
+            --spec                       include spec files
+            --test                       include test files
+            --features                   include features files
+        -x, --exclude PATTERNS           Don't analyze files matching a pattern
+                                         (comma-separated regexp list)
+        -g, --generate                   Generate configuration yaml
+        -v, --version                    Show this version
+        -h, --help                       Show this message
+
+Resources
+---------
+
+Homepage: <http://rails-bestpractices.com>
+
+Github: <http://github.com/flyerhzm/rails_best_practices>
+
+RDoc: <http://rdoc.rails-bestpractices.com>
+
+Team Blog <http://rails-bestpractices.com/blog/posts>
+
+Google Group: <https://groups.google.com/group/rails_best_practices>
+
+Wiki: <http://github.com/flyerhzm/rails_best_practices/wiki>
+
+Issue Tracker: <http://github.com/flyerhzm/rails_best_practices/issues>
+
+Install
+-------
+
+    gem install rails_best_practices
+
+Issue
+-----
+
+If you got NoMethodError or any syntax error, you should use debug mode to detect which file rails_best_practices is parsing and getting the error.
+
+    rails_best_practices -d .
+
+Then give me the error stack and the source code of the file that rails_best_practices is parsing error.
+
+Customize Configuration
+-----------------------
+
+First run
+
+    rails_best_practices -g
+
+to generate <code>rails_best_practices.yml</code> file.
+
+Now you can customize this configuration file, the default configuration is as follows:
+
+    MoveFinderToNamedScopeCheck: { }
+    UseModelAssociationCheck: { }
+    UseScopeAccessCheck: { }
+    AddModelVirtualAttributeCheck: { }
+    ReplaceComplexCreationWithFactoryMethodCheck: { attribute_assignment_count: 2 }
+    MoveModelLogicIntoModelCheck: { use_count: 4 }
+    OveruseRouteCustomizationsCheck: { customize_count: 3 }
+    NeedlessDeepNestingCheck: { nested_count: 2 }
+    NotUseDefaultRouteCheck: {  }
+    KeepFindersOnTheirOwnModelCheck: { }
+    LawOfDemeterCheck: { }
+    UseObserverCheck: { }
+    IsolateSeedDataCheck: { }
+    AlwaysAddDbIndexCheck: { }
+    UseBeforeFilterCheck: { }
+    MoveCodeIntoControllerCheck: { }
+    MoveCodeIntoModelCheck: { use_count: 2 }
+    MoveCodeIntoHelperCheck: { array_count: 3 }
+    ReplaceInstanceVariableWithLocalVariableCheck: { }
+    DryBundlerInCapistranoCheck: { }
+    UseSayWithTimeInMigrationsCheck: { }
+    UseQueryAttributeCheck: { }
+
+You can remove or comment one check to disable it, and you can change the options.
+
+Implementation
+--------------
+
+Move code from Controller to Model
+
+1. Move finder to named_scope (rails2 only)
+2. Use model association
+3. Use scope access
+4. Add model virtual attribute
+5. Replace Complex Creation with Factory Method
+6. Move Model Logic into the Model
+
+RESTful Conventions
+
+1. Overuse route customizations
+2. Needless deep nesting
+3. Not use default route
+
+Model
+
+1. Keep Finders on Their Own Model (rails2 only)
+2. the Law of Demeter
+3. Use Observer
+4. Use Query Attribute
+
+Migration
+
+1. Isolating Seed Data
+2. Always add DB index
+3. Use Say with Time in Migrations
+
+Controller
+
+1. Use before_filter
+
+View
+
+1. Move code into controller
+2. Move code into model
+3. Move code into helper
+4. Replace instance variable with local variable
+
+Deployment
+
+1. Dry bundler in capistrano
+
+Contribute
+----------
+
+If you want to add your rails best practices into the gem, please post your best practices on <http://rails-bestpractices.com>
+
+Contact Us
+----------
+
+We provide rails consulting services, you can contact us by twitter or email.
+
+Follow us on twitter: <http://twitter.com/railsbp>
+
+Send us email: <team@rails-bestpractices.com>
+
+
+Copyright © 2010 Richard Huang (flyerhzm@gmail.com), released under the MIT license

data/lib/rails_best_practices.rb

@@ -1,47 +1,169 @@
 # encoding: utf-8
+
+#--
+# Copyright (c) 2010 Richard Huang (flyerhzm@gmail.com)
+#
+# Permission is hereby granted, free of charge, to any person obtaining
+# a copy of this software and associated documentation files (the
+# "Software"), to deal in the Software without restriction, including
+# without limitation the rights to use, copy, modify, merge, publish,
+# distribute, sublicense, and/or sell copies of the Software, and to
+# permit persons to whom the Software is furnished to do so, subject to
+# the following conditions:
+#
+# The above copyright notice and this permission notice shall be
+# included in all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+# EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+# MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+# NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+# LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+# OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+# WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+#++
+require 'rubygems'
+require 'progressbar'
+require 'colored'
 require 'rails_best_practices/checks'
 require 'rails_best_practices/core'
 
+# RailsBestPractices helps you to analyze your rails code, according to best practices on http://rails-bestpractices.
+# if it finds any violatioins to best practices, it will give you some readable suggestions.
+#
+# The analysis process is partitioned into two parts,
+#
+# 1. prepare process, it checks only model and mailer files, do some preparations, such as remember model names and associations.
+# 2. review process, it checks all files, according to configuration, it really check if codes violate the best practices, if so, remember the violations.
+#
+# After analyzing, output the violations.
 module RailsBestPractices
 
+  DEFAULT_CONFIG = File.join(File.dirname(__FILE__), "..", "rails_best_practices.yml")
+
   class <<self
-    def prepare_files(dir = '.')
-      expand_dirs_to_files File.join(dir, 'app/models')
+    attr_writer :runner
+
+    # generate configuration yaml file.
+    #
+    # @param [String] path where to generate the configuration yaml file
+    def generate(path)
+      @path =  path || '.'
+      FileUtils.cp DEFAULT_CONFIG, File.join(@path, 'config/rails_best_practices.yml')
     end
 
-    def analyze_files(dir = '.', options = {})
-      files = expand_dirs_to_files(dir)
-      files = model_first_sort(files)
-      ['vendor', 'spec', 'test', 'stories', 'features'].each do |pattern|
-        files = ignore_files(files, "#{pattern}/") unless options[pattern]
+    # start checking rails codes.
+    #
+    # there are two steps to check rails codes,
+    #
+    # 1. prepare process, check all model and mailer files.
+    # 2. review process, check all files.
+    #
+    # if there are violations to rails best practices, output them.
+    #
+    # @param [String] path the directory of rails project
+    # @param [Hash] options
+    def start(path, options)
+      @path = path || '.'
+      @options = options
+      Core::Runner.base_path = @path
+      @runner = Core::Runner.new
+      @runner.debug = true if @options['debug']
+
+      if @runner.checks.find { |check| check.is_a? Checks::AlwaysAddDbIndexCheck } &&
+         !review_files.find { |file| file.index "db\/schema.rb" }
+        puts "AlwaysAddDbIndexCheck is disabled as there is no db/schema.rb file in your rails project.".blue
       end
 
-      # Exclude files based on exclude regexes if the option is set.
-      for pattern in options[:exclude]
-        files = ignore_files(files, pattern)
+      @bar = ProgressBar.new('Analyzing', prepare_files.size + review_files.size)
+      process("prepare")
+      process("review")
+      @bar.finish
+
+      output_errors
+      exit @runner.errors.size
+    end
+
+    # process prepare or reivew.
+    #
+    # get all files for the process, analyze each file,
+    # and increment progress bar unless debug.
+    #
+    # @param [String] process the process name, prepare or review.
+    def process(process)
+      files = send("#{process}_files")
+      files.each do |file|
+        @runner.send("#{process}_file", file)
+        @bar.inc unless @options['debug']
       end
+    end
 
-      files
+    # get all files for prepare process.
+    #
+    # @return [Array] all files for prepare process
+    def prepare_files
+      @prepare_files ||= begin
+        files = []
+        ['models', 'mailers'].each do |name|
+          files += expand_dirs_to_files(File.join(@path, 'app', name))
+        end
+        files.compact
+      end
     end
 
+    # get all files for review process.
+    #
+    # @return [Array] all files for review process
+    def review_files
+      @review_files ||= begin
+        files = expand_dirs_to_files(@path)
+        files = file_sort(files)
+        ['vendor', 'spec', 'test', 'features'].each do |pattern|
+          files = file_ignore(files, "#{pattern}/") unless @options[pattern]
+        end
+
+        # Exclude files based on exclude regexes if the option is set.
+        for pattern in @options[:exclude]
+          files = file_ignore(files, pattern)
+        end
+
+        files.compact
+      end
+    end
+
+    # expand all files with extenstion rb, erb, haml and builder under the dirs
+    #
+    # @param [Array] dirs what directories to expand
+    # @return [Array] all files expanded
     def expand_dirs_to_files *dirs
       extensions = ['rb', 'erb', 'haml', 'builder']
 
-      dirs.flatten.map { |p|
-        if File.directory? p
-          Dir[File.join(p, '**', "*.{#{extensions.join(',')}}")]
+      dirs.flatten.map { |entry|
+        next unless File.exist? entry
+        if File.directory? entry
+          Dir[File.join(entry, '**', "*.{#{extensions.join(',')}}")]
         else
-          p
+          entry
         end
       }.flatten
     end
 
-    # for law_of_demeter_check
-    def model_first_sort files
+
+    # sort files, models first, then mailers, and sort other files by characters.
+    #
+    # models and mailers first as for prepare process.
+    #
+    # @param [Array] files
+    # @return [Array] sorted files
+    def file_sort files
       files.sort { |a, b|
-        if a =~ /models\/.*rb/
+        if a =~ Checks::Check::MODEL_FILES
           -1
-        elsif b =~ /models\/.*rb/
+        elsif b =~ Checks::Check::MODEL_FILES
+          1
+        elsif a =~ Checks::Check::MAILER_FILES
+          -1
+        elsif b =~ Checks::Check::MAILER_FILES
           1
         else
           a <=> b
@@ -49,8 +171,24 @@ module RailsBestPractices
       }
     end
 
-    def ignore_files files, pattern
+    # ignore specific files.
+    #
+    # @param [Array] files
+    # @param [Regexp] pattern files match the pattern will be ignored
+    # @return [Array] files that not match the pattern
+    def file_ignore files, pattern
       files.reject { |file| file.index(pattern) }
     end
+
+    # output errors if exist.
+    def output_errors
+      @runner.errors.each { |error| puts error.to_s.red }
+      puts "\nPlease go to http://rails-bestpractices.com to see more useful Rails Best Practices.".green
+      if @runner.errors.empty?
+        puts "\nNo error found. Cool!".green
+      else
+        puts "\nFound #{@runner.errors.size} errors.".red
+      end
+    end
   end
 end

data/lib/rails_best_practices/checks/add_model_virtual_attribute_check.rb

@@ -3,22 +3,55 @@ require 'rails_best_practices/checks/check'
 
 module RailsBestPractices
   module Checks
-    # Check a controller to make sure adding a model virual attribute to simplify model creation.
+    # Make sure to add a model virual attribute to simplify model creation.
     #
-    # Implementation: check arguments of params#[]= before calling save, 
-    # if they have duplicated arguments, then the model may need to add a model virtual attribute.
+    # See the best practice details here http://rails-bestpractices.com/posts/4-add-model-virtual-attribute
+    #
+    # Implementation:
+    #
+    # Prepare process:
+    #   none
+    #
+    # Review process:
+    #   check method define nodes in all controller files,
+    #   if there are more than one [] method calls with the same subject and arguments,
+    #   but assigned to one model's different attribute.
+    #   and after these method calls, there is a save method call for that model, like
+    #
+    #       def create
+    #         @user = User.new(params[:user])
+    #         @user.first_name = params[:full_name].split(' ', 2).first
+    #         @user.last_name = params[:full_name].split(' ', 2).last
+    #         @user.save
+    #       end
+    #
+    #   then the model needs to add a virtual attribute.
     class AddModelVirtualAttributeCheck < Check
-      
-      def interesting_nodes
+
+      def interesting_review_nodes
         [:defn]
       end
-      
-      def interesting_files
+
+      def interesting_review_files
         CONTROLLER_FILES
       end
 
-      def evaluate_start(node)
-        @variables = {}
+      # check method define nodes to see if there are some attribute assignments that can use model virtual attribute instead in review process.
+      #
+      # it will check every attribute assignment nodes and call node of message :save or :save!, if
+      #
+      # 1. there are more than one arguments who contain call node with messages :[] in attribute assignment nodes, e.g.
+      #     @user.first_name = params[:full_name].split(' ').first
+      #     @user.last_name = params[:full_name].split(' ').last
+      # 2. the messages of attribute assignment nodes housld be different (:first_name= , :last_name=)
+      # 3. the argument of call nodes with message :[] should be same (:full_name)
+      # 4. there should be a call node with message :save or :save! after attribute assignment nodes
+      #     @user.save
+      # 5. and the subject of save or save! call node should be the same with the subject of attribute assignment nodes
+      #
+      # then the attribute assignment nodes can add model virtual attribute instead.
+      def review_start_defn(node)
+        @attrasgns = {}
         node.recursive_children do |child|
           case child.node_type
           when :attrasgn
@@ -28,36 +61,77 @@ module RailsBestPractices
           else
           end
         end
-        @variables = nil
       end
-      
+
       private
-      
-      def attribute_assignment(node)
-        variable = node.subject
-        arguments_node = nil
-        node.arguments.recursive_children do |child|
-          if :[] == child.message
-            arguments_node = child
-            break
+        # check an attribute assignment node, if there is a :[] message of call node in the attribute assignment node,
+        # then remember this attribute assignment.
+        #
+        #     s(:attrasgn, s(:ivar, :@user), :first_name=,
+        #       s(:arglist,
+        #         s(:call,
+        #           s(:call,
+        #             s(:call, s(:call, nil, :params, s(:arglist)), :[], s(:arglist, s(:lit, :full_name))),
+        #             :split,
+        #             s(:arglist, s(:str, " "), s(:lit, 2))
+        #           ),
+        #           :first,
+        #           s(:arglist)
+        #         )
+        #       )
+        #     )
+        #
+        # The remember attribute assignments (@attrasgns) are as follows
+        #
+        #     {
+        #       s(:ivar, :@user) =>
+        #         [{
+        #           :message=>:first_name=,
+        #           :arguments=>s(:call, s(:call, nil, :params, s(:arglist)), :[], s(:arglist, s(:lit, :full_name)))
+        #         }]
+        #     }
+        def attribute_assignment(node)
+          subject = node.subject
+          arguments_node = node.arguments.grep_node(:message => :[])
+          return if subject.nil? or arguments_node.nil?
+          @attrasgns[subject] ||= []
+          @attrasgns[subject] << {:message => node.message, :arguments => arguments_node}
+        end
+
+        # check a call node with message :save or :save!,
+        # if there exists an attribute assignment for the subject of this call node,
+        # and if the arguments of this attribute assignments has duplicated entries (different message and same arguments),
+        # then this node needs to add a virtual attribute.
+        #
+        # e.g. this is @attrasgns
+        #     {
+        #       s(:ivar, :@user)=>
+        #         [{
+        #           :message=>:first_name=,
+        #           :arguments=>s(:call, s(:call, nil, :params, s(:arglist)), :[], s(:arglist, s(:lit, :full_name)))
+        #         }, {
+        #           :message=>:last_name=,
+        #           :arguments=>s(:call, s(:call, nil, :params, s(:arglist)), :[], s(:arglist, s(:lit, :full_name)))
+        #         }]
+        #     }
+        # and this is the call node
+        #     s(:call, s(:ivar, :@user), :save, s(:arglist))
+        #
+        # The message of call node is :save,
+        # and the key of @attrasgns is the same as the subject of call node,
+        # and the value of @aatrasgns has different message and same arguments.
+        def call_assignment(node)
+          if [:save, :save!].include? node.message
+            subject = node.subject
+            add_error "add model virtual attribute (for #{subject})" if params_dup?(@attrasgns[subject].collect {|h| h[:arguments]})
           end
         end
-        return if variable.nil? or arguments_node.nil?
-        @variables[variable] ||= []
-        @variables[variable] << {:message => node.message, :arguments => arguments_node}
-      end
-      
-      def call_assignment(node)
-        if node.message == :save
-          variable = node.subject
-          add_error "add model virtual attribute (for #{variable})" if params_dup?(@variables[variable].collect {|h| h[:arguments]})
+
+        # if the nodes are duplicated.
+        def params_dup?(nodes)
+          return false if nodes.nil?
+          !nodes.dups.empty?
         end
-      end
-      
-      def params_dup?(nodes)
-        return false if nodes.nil?
-        !nodes.dups.empty?
-      end
     end
   end
 end