foodcritic 1.4.0 → 1.5.0

data/lib/foodcritic/ast.rb

@@ -0,0 +1,22 @@
+module FoodCritic
+  module AST
+
+    private
+
+    def ast_hash_node?(node)
+      node.first.respond_to?(:first) and node.first.first == :assoc_new
+    end
+
+    def ast_node_has_children?(node)
+      node.respond_to?(:first)
+    end
+
+    # If the provided node is the line / column information.
+    def position_node?(node)
+      node.respond_to?(:length) and node.length == 2 and
+        node.respond_to?(:all?) and node.all?{|child| child.respond_to?(:to_i)}
+    end
+
+  end
+
+end

data/lib/foodcritic/chef.rb

@@ -3,43 +3,50 @@ module FoodCritic
   # Encapsulates functions that previously were calls to the Chef gem.
   module Chef
 
-    # The set of methods in the Chef DSL
-    #
-    # @return [Array] Array of method symbols
     def chef_dsl_methods
       load_metadata
       @dsl_metadata[:dsl_methods].map(&:to_sym)
     end
 
-    # Is the specified attribute valid for the type of resource? Note that this
-    # method will return true if the resource_type is not recognised.
-    #
-    # @param [Symbol] resource_type The type of Chef resource
-    # @param [Symbol] attribute_name The attribute name
-    # @return [Boolean] False if the attribute is known not to be valid
+    # Is the specified action valid for the type of resource?
+    def resource_action?(resource_type, action)
+      resource_check?(:actions, resource_type, action)
+    end
+
+    # Is the specified attribute valid for the type of resource?
     def resource_attribute?(resource_type, attribute_name)
-      if resource_type.to_s.empty? || attribute_name.to_s.empty?
-        raise ArgumentError, "Arguments cannot be nil or empty."
-      end
-      load_metadata
-      resource_attributes = @dsl_metadata[:attributes]
-      return true unless resource_attributes.include?(resource_type.to_sym)
-      resource_attributes[resource_type.to_sym].include?(attribute_name.to_s)
+      resource_check?(:attributes, resource_type, attribute_name)
     end
 
     # Is this a valid Lucene query?
-    #
-    # @param [String] query The query to check for syntax errors
-    # @return [Boolean] True if the query is well-formed
     def valid_query?(query)
       raise ArgumentError, "Query cannot be nil or empty" if query.to_s.empty?
+
+      # Attempt to create a search query parser
       search = FoodCritic::Chef::Search.new
       search.create_parser(search.chef_search_grammars)
-      search.parser? ? (! search.parser.parse(query.to_s).nil?) : true
+
+      if search.parser?
+        search.parser.parse(query.to_s)
+      else
+        # If we didn't manage to get a parser then we can't know if the query
+        # is valid or not.
+        true
+      end
     end
 
     private
 
+    # To avoid the runtime hit of loading the Chef gem and its dependencies
+    # we load the DSL metadata from a JSON file shipped with our gem.
+    #
+    # The DSL metadata therefore reflects the version of Chef in the gemset
+    # where foodcritic was built, rather than the version in the local user
+    # gemset.
+    #
+    # TODO: Now that the effective version of Chef to check with can be passed
+    # on the command-line we should bundle metadata for historical Chef gem
+    # versions.
     def load_metadata
       metadata_path = File.join(File.dirname(__FILE__), '..', '..',
         'chef_dsl_metadata.json')
@@ -47,14 +54,28 @@ module FoodCritic
         :symbolize_keys => true)
     end
 
-    # Chef Search
+    def resource_check?(key, resource_type, field)
+      if resource_type.to_s.empty? || field.to_s.empty?
+        raise ArgumentError, "Arguments cannot be nil or empty."
+      end
+
+      load_metadata
+      resource_fields = @dsl_metadata[key]
+
+      # If the resource type is not recognised then it may be a user-defined
+      # resource. We could introspect these but at present we simply return
+      # true.
+      return true unless resource_fields.include?(resource_type.to_sym)
+
+      # Otherwise the resource field must exist in our metadata to succeed
+      resource_fields[resource_type.to_sym].include?(field.to_s)
+    end
+
     class Search
 
       # The search grammars that ship with any Chef gems installed locally.
       # These are returned in descending version order (a newer Chef version
       #   could break our ability to load the grammar).
-      #
-      # @return [Array] File paths of Chef search grammars installed locally.
       def chef_search_grammars
         Gem.path.map do |gem_path|
           Dir["#{gem_path}/gems/chef-*/**/lucene.treetop"]
@@ -62,32 +83,26 @@ module FoodCritic
       end
 
       # Create the search parser from the first loadable grammar.
-      #
-      # @param [Array] grammar_paths Full paths to candidate treetop grammars
       def create_parser(grammar_paths)
         @search_parser ||= grammar_paths.inject(nil) do |parser,lucene_grammar|
             begin
               break parser unless parser.nil?
-              # don't instantiate custom nodes
+              # Don't instantiate custom nodes
               Treetop.load_from_string(
                 IO.read(lucene_grammar).gsub(/<[^>]+>/, ''))
               LuceneParser.new
             rescue
-              # silently swallow and try the next grammar
+              # Silently swallow and try the next grammar
             end
         end
       end
 
       # Has the search parser been loaded?
-      #
-      # @return [Boolean] True if the search parser has been loaded.
       def parser?
         ! @search_parser.nil?
       end
 
       # The search parser
-      #
-      # @return [LuceneParser] The search parser
       def parser
         @search_parser
       end

data/lib/foodcritic/command_line.rb

@@ -45,7 +45,17 @@ module FoodCritic
           options[:version] = true
         end
       end
-      @parser.parse!(args) unless show_help?
+      # -v is not implemented but OptionParser gives the Foodcritic's version
+      # if that flag is passed
+      if args.include? '-v'
+        help
+      else
+        begin
+          @parser.parse!(args) unless show_help?
+        rescue OptionParser::InvalidOption => e
+          e.recover args
+        end
+      end
     end
 
     # Show the command help to the end user?
@@ -66,7 +76,7 @@ module FoodCritic
     #
     # @return [Boolean] True if the version should be shown.
     def show_version?
-      @options.key?(:version) and @original_args != ['-v']
+      @options.key?(:version)
     end
 
     # The version string.

data/lib/foodcritic/domain.rb

@@ -4,14 +4,11 @@ module FoodCritic
   class Warning
     attr_reader :rule, :match
 
-    # Create a new warning
+    # Create a new warning.
+    #
+    #     Warning.new(rule, :filename => 'foo/recipes.default.rb',
+    #       :line => 5, :column=> 40)
     #
-    # @param [FoodCritic::Rule] rule The rule which raised this warning
-    # @param [Hash] match The match data
-    # @option match [String] :filename The filename the warning was raised
-    #   against
-    # @option match [Integer] :line The identified line
-    # @option match [Integer] :column The identified column
     def initialize(rule, match={})
       @rule, @match = rule, match
     end
@@ -22,36 +19,29 @@ module FoodCritic
 
     attr_reader :cookbook_paths, :warnings
 
-    # Create a new review
-    #
-    # @param [Array] cookbook_paths The path this review was performed against
-    # @param [Array] warnings The warnings raised in this review
-    # @param [Boolean] is_failed Have warnings been raised that mean this
-    #   should be considered failed?
     def initialize(cookbook_paths, warnings, is_failed)
       @cookbook_paths = Array(cookbook_paths)
       @warnings = warnings
       @is_failed = is_failed
     end
 
-    # Provided for backwards compatibility
-    # @deprecated Multiple cookbook paths may be provided.
+    # Provided for backwards compatibility. Deprecated and will be removed in a
+    # later version.
     def cookbook_path
       @cookbook_paths.first
     end
 
     # If this review has failed or not.
-    #
-    # @return [Boolean] True if this review has failed.
     def failed?
       @is_failed
     end
 
-    # Returns a string representation of this review.
-    #
-    # @return [String] Review as a string, this representation is liable to
-    #   change.
+    # Returns a string representation of this review. This representation is
+    # liable to change.
     def to_s
+      # Sorted by filename and line number.
+      #
+      #     FC123: My rule name: foo/recipes/default.rb
       @warnings.map do |w|
         ["#{w.rule.code}: #{w.rule.name}: #{w.match[:filename]}",
          w.match[:line].to_i]
@@ -63,32 +53,23 @@ module FoodCritic
 
   # A rule to be matched against.
   class Rule
-    attr_accessor :code, :name, :applies_to, :cookbook, :recipe, :provider, :resource
+    attr_accessor :code, :name, :applies_to, :cookbook, :recipe, :provider,
+      :resource, :metadata, :library, :template
     attr_writer :tags
 
-    # Create a new rule
-    #
-    # @param [String] code The short unique identifier for this rule,
-    #   e.g. 'FC001'
-    # @param [String] name The short descriptive name of this rule presented to
-    #   the end user.
     def initialize(code, name)
       @code, @name = code, name
       @tags = [code]
       @applies_to = Proc.new {|version| true}
     end
 
-    # The tags associated with this rule.
-    # A rule is always tagged with the tags 'any' and the rule code.
-    #
-    # @return [Array] The tags associated.
+    # The tags associated with this rule. Rule is always tagged with the tag
+    # `any` and the rule code.
     def tags
       ['any'] + @tags
     end
 
     # Returns a string representation of this rule.
-    #
-    # @return [String] Rule as a string.
     def to_s
       "#{@code}: #{@name}"
     end

data/lib/foodcritic/dsl.rb

@@ -1,74 +1,69 @@
 require 'pathname'
 
-# FoodCritic is a lint tool for Chef cookbooks.
 module FoodCritic
 
-  # The DSL methods exposed for defining rules.
+  # The DSL methods exposed for defining rules. A minimal example rule:
+  #
+  #     rule "FC123", "My rule name" do
+  #       tags %w{style attributes}
+  #         recipe do |ast|
+  #           ## Rule implementation body
+  #         end
+  #     end
+  #
+  # * Each rule is defined within a `rule` block that defines the code and name
+  #   of the rule.
+  # * Each rule block may contain further nested blocks for the components of
+  #   the cookbook that it is interested in linting.
+  #   For example `cookbook`, `recipe` or `library`.
+  #
+  # * Further DSL methods are available to define the `tags` and Chef versions
+  #   the rule `applies_to`.
+  #
+
   class RuleDsl
     attr_reader :rules
 
     include Api
 
-    # Define a new rule
-    #
-    # @param [String] code The short unique identifier for this rule,
-    #   e.g. 'FC001'
-    # @param [String] name The short descriptive name of this rule presented to
-    #   the end user.
-    # @param [Block] block The rule definition
+    # Define a new rule, the outer block of a rule definition.
     def rule(code, name, &block)
       @rules = [] if @rules.nil?
       @rules << Rule.new(code, name)
       yield self
     end
 
-    # Add tags to the rule which can be used to filter the rules to be applied.
-    #
-    # @param [Array] tags The tags associated with this rule.
+    # Add tags to the rule which can be used by the end user to filter the rules
+    # to be applied.
     def tags(tags)
       rules.last.tags += tags
     end
 
-    # Limit the versions that this rule can be seen to apply to.
-    #
-    # @param [block] block Your version constraint logic.
+    # Alternative to tags. Commonly used to constrain a rule to run only when
+    # linting specific Chef versions.
     def applies_to(&block)
       rules.last.applies_to = block
     end
 
-    # Define a matcher that will be passed the AST with this method.
-    #
-    # @param [block] block Your implemented matcher that returns a match Hash.
-    def recipe(&block)
-      rules.last.recipe = block
+    def self.rule_block(name)
+      define_method(name) do |&block|
+        rules.last.send("#{name}=".to_sym, block)
+      end
     end
 
-    # Define a matcher that will be passed the AST with this method.
-    #
-    # @param [block] block Your implemented matcher that returns a match Hash.
-    def resource(&block)
-      rules.last.resource = block
-    end
+    # The most frequently used block within a rule. A slight misnomer because
+    # `recipe` rule blocks are also evaluated against providers.
+    rule_block :recipe
 
-    # Define a matcher that will be passed the AST with this method.
-    #
-    # @param [block] block Your implemented matcher that returns a match Hash.
-    def provider(&block)
-      rules.last.provider = block
-    end
 
-    # Define a matcher that will be passed the cookbook path with this method.
-    #
-    # @param [block] block Your implemented matcher that returns a match Hash.
-    def cookbook(&block)
-      rules.last.cookbook = block
-    end
+    rule_block :cookbook
+    rule_block :metadata
+    rule_block :resource
+    rule_block :provider
+    rule_block :library
+    rule_block :template
 
-    # Load the ruleset
-    #
-    # @param [Array] paths The paths to the rulesets to load
-    # @return [Array] The loaded rules, ready to be matched against provided
-    #   cookbooks.
+    # Load the ruleset(s).
     def self.load(paths, with_repl)
       dsl = RuleDsl.new
       paths.map do |path|
@@ -76,9 +71,13 @@ module FoodCritic
       end.flatten.each do |path|
         dsl.instance_eval(File.read(path), path)
       end
+
+      # Drop into the REPL for exploratory rule development.
       dsl.instance_eval { binding.pry } if with_repl
+
       dsl.rules
     end
+
   end
 
 end

data/lib/foodcritic/linter.rb

@@ -5,22 +5,21 @@ require 'gherkin/tag_expression'
 require 'set'
 
 module FoodCritic
-
   # The main entry point for linting your Chef cookbooks.
   class Linter
 
     include FoodCritic::Api
+    include FoodCritic::REPL
 
-    # The default version that will be used to determine relevant rules
+    # The default version that will be used to determine relevant rules. This
+    # can be over-ridden at the command line with the `--chef-version` option.
     DEFAULT_CHEF_VERSION = "0.10.10"
 
-    # Perform option parsing from the provided arguments and do a lint check
-    # based on those arguments.
-    #
-    # @param [Array] args The command-line arguments to parse
-    # @return [Array] Pair - the first item is string output, the second is the
-    #   exit code.
+    # Perform a lint check. This method is intended for use by the command-line
+    # wrapper. If you are programatically using foodcritic you should use
+    # `#check` below.
     def self.check(cmd_line)
+      # The first item is the string output, the second is exit code.
       return [cmd_line.help, 0] if cmd_line.show_help?
       return [cmd_line.version, 0] if cmd_line.show_version?
       if ! cmd_line.valid_grammar?
@@ -34,113 +33,131 @@ module FoodCritic
       end
     end
 
-    # Create a new Linter.
-    def initialize
-
-    end
-
     # Review the cookbooks at the provided path, identifying potential
     # improvements.
     #
-    # @param [Array] cookbook_paths The file path(s) to the individual
-    #   cookbook(s) being checked
-    # @param [Hash] options Options to apply to the linting
-    # @option options [Array] include_rules Paths to local rules to apply
-    # @option options [Array] tags The tags to filter rules based on
-    # @option options [Array] fail_tags The tags to fail the build on
-    # @return [FoodCritic::Review] A review of your cookbooks, with any
-    #   warnings issued.
+    # The `options` are a hash where the valid keys are:
+    #
+    # * `:include_rules` - Paths to additional rules to apply
+    # * `:tags` - The tags to filter rules based on
+    # * `:fail_tags` - The tags to fail the build on
+    # * `:exclude_paths` - Paths to exclude from linting
+    #
     def check(cookbook_paths, options)
-      raise ArgumentError, "Cookbook paths are required" if cookbook_paths.nil?
-      cookbook_paths = Array(cookbook_paths)
-      if cookbook_paths.empty?
-        raise ArgumentError, "Cookbook paths cannot be empty"
-      end
-
-      options = {:tags => [], :fail_tags => [],
-                 :include_rules => []}.merge(options)
-
-      @last_cookbook_paths, @last_options = cookbook_paths, options
-      load_rules unless defined? @rules
-      warnings = []; last_dir = nil; matched_rule_tags = Set.new
 
-      active_rules = @rules.select do |rule|
-        matching_tags?(options[:tags], rule.tags) and
-        applies_to_version?(rule, options[:chef_version] || DEFAULT_CHEF_VERSION)
-      end
-      files_to_process(cookbook_paths).each do |file|
-        cookbook_dir = Pathname.new(
-          File.join(File.dirname(file), '..')).cleanpath
-        ast = read_ast(file)
-        active_rules.each do |rule|
-          rule_matches = matches(rule.recipe, ast, file)
-          if File.basename(File.dirname(file)) == 'providers'
-            rule_matches += matches(rule.provider, ast, file)
-          end
-          if File.basename(File.dirname(file)) == 'resources'
-            rule_matches += matches(rule.resource, ast, file)
-          end
-          if last_dir != cookbook_dir
-            rule_matches += matches(rule.cookbook, cookbook_dir)
-          end
-          rule_matches.each do |match|
-            warnings << Warning.new(rule, {:filename => file}.merge(match))
-            matched_rule_tags << rule.tags
+      cookbook_paths = sanity_check_cookbook_paths(cookbook_paths)
+      options = setup_defaults(options)
+
+      # Enable checks to be easily repeated at the REPL
+      with_repl(cookbook_paths, options) do
+        warnings = []; last_dir = nil; matched_rule_tags = Set.new
+
+        load_rules
+
+        # Loop through each file to be processed and apply the rules
+        files_to_process(cookbook_paths, options[:exclude_paths]).each do |file|
+          ast = read_ast(file)
+          active_rules(options).each do |rule|
+            rule_matches = matches(rule.recipe, ast, file)
+
+            if dsl_method_for_file(file)
+              rule_matches += matches(rule.send(dsl_method_for_file(file)),
+                ast, file)
+            end
+
+            per_cookbook_rules(last_dir, file) do
+              if File.basename(file) == 'metadata.rb'
+                rule_matches += matches(rule.metadata, ast, file)
+              end
+              rule_matches += matches(rule.cookbook, cookbook_dir(file))
+            end
+
+            # Convert the matches into warnings
+            rule_matches.each do |match|
+              warnings << Warning.new(rule, {:filename => file}.merge(match))
+              matched_rule_tags << rule.tags
+            end
           end
+          last_dir = cookbook_dir(file)
         end
-        last_dir = cookbook_dir
-      end
 
-      @review = Review.new(cookbook_paths, warnings,
-                  should_fail_build?(options[:fail_tags], matched_rule_tags))
-
-      binding.pry if options[:repl]
-      @review
-    end
-
-    # Convenience method to repeat the last check. Intended to be used from the
-    # REPL.
-    def recheck
-      check(@last_cookbook_paths, @last_options)
+        Review.new(cookbook_paths, warnings,
+          should_fail_build?(options[:fail_tags], matched_rule_tags))
+      end
     end
 
     # Load the rules from the (fairly unnecessary) DSL.
     def load_rules
-      @rules = RuleDsl.load([File.join(File.dirname(__FILE__), 'rules.rb')] +
-        @last_options[:include_rules], @last_options[:repl])
+      load_rules!(@last_options) unless defined? @rules
     end
 
-    alias_method :reset_rules, :load_rules
-
-    # Convenience method to retrieve the last review. Intended to be used from
-    # the REPL.
-    #
-    # @return [Review] The last review performed.
-    def review
-      @review
+    def load_rules!(options)
+      @rules = RuleDsl.load([File.join(File.dirname(__FILE__), 'rules.rb')] +
+        options[:include_rules], options[:repl])
     end
 
     private
 
     # Some rules are version specific.
-    #
-    # @param [FoodCritic::Rule] rule The rule determine applicability for
-    # @param [String] version The version of Chef
-    # @return [Boolean] True if the rule applies to this version of Chef
     def applies_to_version?(rule, version)
       return true unless version
       rule.applies_to.yield(Gem::Version.create(version))
     end
 
+    def active_rules(options)
+      @rules.select do |rule|
+        matching_tags?(options[:tags], rule.tags) and
+        applies_to_version?(rule, options[:chef_version] || DEFAULT_CHEF_VERSION)
+      end
+    end
+
+    def cookbook_dir(file)
+      Pathname.new(File.join(File.dirname(file),
+        case File.basename(file)
+          when 'metadata.rb' then ''
+          when /\.erb$/ then '../..'
+          else '..'
+        end)).cleanpath
+    end
+
+    def dsl_method_for_file(file)
+      dir_mapping = {
+        'libraries' => :library,
+        'providers' => :provider,
+        'resources' => :resource,
+        'templates' => :template
+      }
+      if file.end_with? '.erb'
+        dir_mapping[File.basename(File.dirname(File.dirname(file)))]
+      else
+        dir_mapping[File.basename(File.dirname(file))]
+      end
+    end
+
+    # Return the files within a cookbook tree that we are interested in trying
+    # to match rules against.
+    def files_to_process(dirs, exclude_paths = [])
+      files = []
+      dirs.each do |dir|
+        exclusions = Dir.glob(exclude_paths.map{|p| File.join(dir, p)})
+        if File.directory? dir
+          cookbook_glob = '{metadata.rb,{attributes,libraries,providers,recipes,resources}/*.rb,templates/*/*.erb}'
+          files += (Dir.glob(File.join(dir, cookbook_glob)) +
+            Dir.glob(File.join(dir, "*/#{cookbook_glob}")) - exclusions)
+        else
+          files << dir unless exclusions.include?(dir)
+        end
+      end
+      files
+    end
+
     # Invoke the DSL method with the provided parameters.
-    #
-    # @param [Proc] match_method Proc to invoke
-    # @param params Parameters for the proc
-    # @return [Array] The returned matches
     def matches(match_method, *params)
       return [] unless match_method.respond_to?(:yield)
       matches = match_method.yield(*params)
       return [] unless matches.respond_to?(:each)
+
+      # We convert Nokogiri nodes to matches transparently
       matches.map do |m|
         if m.respond_to?(:node_name)
           match(m)
@@ -152,49 +169,35 @@ module FoodCritic
       end.flatten
     end
 
-    # Return the files within a cookbook tree that we are interested in trying
-    # to match rules against.
-    #
-    # @param [Array<String>] dirs The cookbook path(s)
-    # @return [Array] The files underneath the provided paths to be
-    #   processed.
-    def files_to_process(dirs)
-      files = []
+    # We use the Gherkin (Cucumber) syntax to specify tags.
+    def matching_tags?(tag_expr, tags)
+      Gherkin::TagExpression.new(tag_expr).eval(tags.map do |t|
+        Gherkin::Formatter::Model::Tag.new(t, 1)
+      end)
+    end
 
-      dirs.each do |dir|
-        if File.directory? dir
-          cookbook_glob = '{attributes,providers,recipes,resources}/*.rb'
-          files += Dir.glob(File.join(dir, cookbook_glob)) +
-            Dir.glob(File.join(dir, "*/#{cookbook_glob}"))
-        else
-          files << dir
-        end
+    def per_cookbook_rules(last_dir, file)
+      yield if last_dir != cookbook_dir(file)
+    end
+
+    def sanity_check_cookbook_paths(cookbook_paths)
+      raise ArgumentError, "Cookbook paths are required" if cookbook_paths.nil?
+      cookbook_paths = Array(cookbook_paths)
+      if cookbook_paths.empty?
+        raise ArgumentError, "Cookbook paths cannot be empty"
       end
+      cookbook_paths
+    end
 
-      files
+    def setup_defaults(options)
+      {:tags => [], :fail_tags => [],
+                 :include_rules => [], :exclude_paths => []}.merge(options)
     end
 
-    # Whether to fail the build.
-    #
-    # @param [Array] fail_tags The tags that should cause the build to fail, or
-    #   special value 'any' for any tag.
-    # @param [Set] matched_tags The tags of warnings we have matches for
-    # @return [Boolean] True if the build should be failed
     def should_fail_build?(fail_tags, matched_tags)
       return false if fail_tags.empty?
       matched_tags.any?{|tags| matching_tags?(fail_tags, tags)}
     end
 
-    # Evaluate the specified tags
-    #
-    # @param [Array] tag_expr Tag expressions
-    # @param [Array] tags Tags to match against
-    # @return [Boolean] True if the tags match
-    def matching_tags?(tag_expr, tags)
-      Gherkin::TagExpression.new(tag_expr).eval(tags.map do |t|
-        Gherkin::Formatter::Model::Tag.new(t, 1)
-      end)
-    end
-
   end
 end