haml_lint 0.13.0 → 0.14.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 343fc1d49926d0ac21d87fbfc26b93c518d690fc
-  data.tar.gz: 79d58c8fe3e0ded6c8cde5dee115276d84720fc1
+  metadata.gz: fdd406c711a12f70bba2b26982550e7f190b2c61
+  data.tar.gz: 2cd4a631a543de9987408c30a4367d18bff33d6b
 SHA512:
-  metadata.gz: 26259ff8ae9e582436736b4830a90c1256259a32d9d36372ec9dc8e823582c1cb4682bf2edb38c5db78b1d325c1d2baadd45f05fa8a1a3e6153aaa610bd38201
-  data.tar.gz: c30b1bcc9d65705bc944bd90e6743e2f26e35ebcb45df0158ad8db7702a7b03e7f94fe212265d91c88d780bbd112239bf88679f3e1e7614c585447f46d626468
+  metadata.gz: 89371444076d421e9589f2b34b3867b6b0387f0f07af00f119a520d20b296b3a77088e425e36cf5b29a1b043cd24e4987b15557a9bc8c0e502985b5c124d0014
+  data.tar.gz: 3053c5a7d28d8cc7e242bb0346cc83e8e6a65935dad36042678eedd2d8a21f8784085c67887a528baec7698fae8e2ceb958a76e5ce787e251c41b2ffa6f346ef

data/config/default.yml

@@ -61,6 +61,7 @@ linters:
       - Style/AlignParameters
       - Style/BlockNesting
       - Style/FileName
+      - Style/FinalNewline
       - Style/IfUnlessModifier
       - Style/IndentationWidth
       - Style/Next

data/lib/haml_lint/cli.rb

@@ -1,3 +1,4 @@
+require 'haml_lint'
 require 'haml_lint/options'
 
 require 'sysexits'
@@ -5,8 +6,8 @@ require 'sysexits'
 module HamlLint
   # Command line application interface.
   class CLI
-    attr_accessor :options
-
+    # Create a CLI that outputs to the specified logger.
+    #
     # @param logger [HamlLint::Logger]
     def initialize(logger)
       @log = logger
@@ -16,7 +17,7 @@ module HamlLint
     # based on those arguments.
     #
     # @param args [Array<String>] command line arguments
-    # @return [Fixnum] exit status returned by the application
+    # @return [Integer] exit status code
     def run(args)
       options = HamlLint::Options.new.parse(args)
       act_on_options(options)
@@ -28,6 +29,9 @@ module HamlLint
 
     attr_reader :log
 
+    # Given the provided options, execute the appropriate command.
+    #
+    # @return [Integer] exit status code
     def act_on_options(options)
       log.color_enabled = options.fetch(:color, log.tty?)
 
@@ -48,6 +52,8 @@ module HamlLint
       end
     end
 
+    # Outputs a message and returns an appropriate error code for the specified
+    # exception.
     def handle_exception(ex)
       case ex
       when HamlLint::Exceptions::ConfigurationError
@@ -69,21 +75,27 @@ module HamlLint
       end
     end
 
+    # Scans the files specified by the given options for lints.
+    #
+    # @return [Integer] exit status code
     def scan_for_lints(options)
       report = Runner.new.run(options)
       print_report(report, options)
       report.failed? ? Sysexits::EX_DATAERR : Sysexits::EX_OK
     end
 
+    # Outputs a report of the linter run using the specified reporter.
     def print_report(report, options)
-      reporter = options.fetch(:reporter, Reporter::DefaultReporter).new(log, report)
-      reporter.report_lints
+      reporter = options.fetch(:reporter,
+                               HamlLint::Reporter::DefaultReporter).new(log)
+      reporter.display_report(report)
     end
 
+    # Outputs a list of all currently available linters.
     def print_available_linters
       log.info 'Available linters:'
 
-      linter_names = LinterRegistry.linters.map do |linter|
+      linter_names = HamlLint::LinterRegistry.linters.map do |linter|
         linter.name.split('::').last
       end
 
@@ -92,10 +104,11 @@ module HamlLint
       end
     end
 
+    # Outputs a list of currently available reporters.
     def print_available_reporters
       log.info 'Available reporters:'
 
-      reporter_names = Reporter.descendants.map do |reporter|
+      reporter_names = HamlLint::Reporter.descendants.map do |reporter|
         reporter.name.split('::').last.sub(/Reporter$/, '').downcase
       end
 
@@ -104,14 +117,18 @@ module HamlLint
       end
     end
 
+    # Outputs help documentation.
     def print_help(options)
       log.log options[:help]
     end
 
+    # Outputs the application name and version.
     def print_version
-      log.log "#{APP_NAME} #{HamlLint::VERSION}"
+      log.log "#{HamlLint::APP_NAME} #{HamlLint::VERSION}"
     end
 
+    # Outputs the backtrace of an exception with instructions on how to report
+    # the issue.
     def print_unexpected_exception(ex)
       log.bold_error ex.message
       log.error ex.backtrace.join("\n")

data/lib/haml_lint/configuration.rb

@@ -1,6 +1,12 @@
 module HamlLint
-  # Stores configuration for haml-lint.
+  # Stores runtime configuration for the application.
+  #
+  # The purpose of this class is to validate and ensure all configurations
+  # satisfy some basic pre-conditions so other parts of the application don't
+  # have to check the configuration for errors. It should have no knowledge of
+  # how these configuration values are ultimately used.
   class Configuration
+    # Internal hash storing the configuration.
     attr_reader :hash
 
     # Creates a configuration from the given options hash.
@@ -11,6 +17,14 @@ module HamlLint
       validate
     end
 
+    # Access the configuration as if it were a hash.
+    #
+    # @param key [String]
+    # @return [Array,Hash,Number,String]
+    def [](key)
+      @hash[key]
+    end
+
     # Compares this configuration with another.
     #
     # @param other [HamlLint::Configuration]
@@ -30,19 +44,9 @@ module HamlLint
           linter.name.split('::').last
         when HamlLint::Linter
           linter.name
-        else
-          linter.to_s
         end
 
-      smart_merge(@hash['linters']['ALL'],
-                  @hash['linters'].fetch(linter_name, {})).freeze
-    end
-
-    # Returns whether the specified linter is enabled by this configuration.
-    #
-    # @param linter [HamlLint::Linter,String]
-    def linter_enabled?(linter)
-      for_linter(linter)['enabled'] != false
+      @hash['linters'].fetch(linter_name, {}).dup.freeze
     end
 
     # Merges the given configuration with this one, returning a new
@@ -56,18 +60,14 @@ module HamlLint
 
     private
 
-    # Validates the configuration for any invalid options, normalizing it where
-    # possible.
-    def validate
-      @hash = convert_nils_to_empty_hashes(@hash)
-      ensure_linter_section_exists(@hash)
-    end
-
+    # Merge two hashes such that nested hashes are merged rather than replaced.
+    #
+    # @param parent [Hash]
+    # @param child [Hash]
+    # @return [Hash]
     def smart_merge(parent, child)
       parent.merge(child) do |_key, old, new|
         case old
-        when Array
-          old + Array(new)
         when Hash
           smart_merge(old, new)
         else
@@ -76,21 +76,43 @@ module HamlLint
       end
     end
 
-    def ensure_linter_section_exists(hash)
-      hash['linters'] ||= {}
-      hash['linters']['ALL'] ||= {}
+    # Validates the configuration for any invalid options, normalizing it where
+    # possible.
+    def validate
+      ensure_exclude_option_array_exists
+      ensure_linter_section_exists
+      ensure_linter_include_exclude_arrays_exist
+      ensure_linter_severity_valid
+    end
+
+    # Ensures the `exclude` global option is an array.
+    def ensure_exclude_option_array_exists
+      @hash['exclude'] = Array(@hash['exclude'])
+    end
+
+    # Ensures the `linters` configuration section exists.
+    def ensure_linter_section_exists
+      @hash['linters'] ||= {}
+    end
+
+    # Ensure `include` and `exclude` options for linters are arrays
+    # (since users can specify a single string glob pattern for convenience)
+    def ensure_linter_include_exclude_arrays_exist
+      @hash['linters'].keys.each do |linter_name|
+        %w[include exclude].each do |option|
+          linter_config = @hash['linters'][linter_name]
+          linter_config[option] = Array(linter_config[option])
+        end
+      end
     end
 
-    def convert_nils_to_empty_hashes(hash)
-      hash.each_with_object({}) do |(key, value), h|
-        h[key] =
-          case value
-          when nil  then {}
-          when Hash then convert_nils_to_empty_hashes(value)
-          else
-            value
-          end
-        h
+    def ensure_linter_severity_valid
+      @hash['linters'].each do |linter_name, linter_config|
+        severity = linter_config['severity']
+        unless [nil, 'warning', 'error'].include?(severity)
+          raise HamlLint::Exceptions::ConfigurationError,
+                "Invalid severity '#{severity}' specified for #{linter_name}"
+        end
       end
     end
   end

data/lib/haml_lint/configuration_loader.rb

@@ -4,10 +4,12 @@ require 'yaml'
 module HamlLint
   # Manages configuration file loading.
   class ConfigurationLoader
-    DEFAULT_CONFIG_PATH = File.join(HAML_LINT_HOME, 'config', 'default.yml')
+    DEFAULT_CONFIG_PATH = File.join(HamlLint::HOME, 'config', 'default.yml')
     CONFIG_FILE_NAME = '.haml-lint.yml'
 
     class << self
+      # Load configuration file given the current working directory the
+      # application is running within.
       def load_applicable_config
         directory = File.expand_path(Dir.pwd)
         config_file = possible_config_files(directory).find(&:file?)
@@ -19,33 +21,42 @@ module HamlLint
         end
       end
 
+      # Loads the built-in default configuration.
       def default_configuration
         @default_config ||= load_from_file(DEFAULT_CONFIG_PATH)
       end
 
       # Loads a configuration, ensuring it extends the default configuration.
+      #
+      # @param file [String]
+      # @return [HamlLint::Configuration]
       def load_file(file)
         config = load_from_file(file)
 
         default_configuration.merge(config)
-      rescue => error
+      rescue Psych::SyntaxError, Errno::ENOENT => error
         raise HamlLint::Exceptions::ConfigurationError,
               "Unable to load configuration from '#{file}': #{error}",
               error.backtrace
       end
 
+      # Creates a configuration from the specified hash, ensuring it extends the
+      # default configuration.
+      #
+      # @param hash [Hash]
+      # @return [HamlLint::Configuration]
       def load_hash(hash)
         config = HamlLint::Configuration.new(hash)
 
         default_configuration.merge(config)
-      rescue => error
-        raise HamlLint::Exceptions::ConfigurationError,
-              "Unable to load configuration from '#{file}': #{error}",
-              error.backtrace
       end
 
       private
 
+      # Parses and loads a configuration from the given file.
+      #
+      # @param file [String]
+      # @return [HamlLint::Configuration]
       def load_from_file(file)
         hash =
           if yaml = YAML.load_file(file)
@@ -57,6 +68,11 @@ module HamlLint
         HamlLint::Configuration.new(hash)
       end
 
+      # Returns a list of possible configuration files given the context of the
+      # specified directory.
+      #
+      # @param directory [String]
+      # @return [Array<Pathname>]
       def possible_config_files(directory)
         files = Pathname.new(directory)
                         .enum_for(:ascend)

data/lib/haml_lint/constants.rb

@@ -1,6 +1,6 @@
 # Global application constants.
 module HamlLint
-  HAML_LINT_HOME = File.expand_path(File.join(File.dirname(__FILE__), '..', '..'))
+  HOME = File.expand_path(File.join(File.dirname(__FILE__), '..', '..'))
   APP_NAME = 'haml-lint'
 
   REPO_URL = 'https://github.com/brigade/haml-lint'

data/lib/haml_lint/document.rb

@@ -0,0 +1,102 @@
+module HamlLint
+  # Represents a parsed Haml document and its associated metadata.
+  class Document
+    # File name given to source code parsed from just a string.
+    STRING_SOURCE = '(string)'
+
+    # @return [HamlLint::Configuration] Configuration used to parse template
+    attr_reader :config
+
+    # @return [String] Haml template file path
+    attr_reader :file
+
+    # @return [HamlLint::Tree::Node] Root of the parse tree
+    attr_reader :tree
+
+    # @return [String] original source code
+    attr_reader :source
+
+    # @return [Array<String>] original source code as an array of lines
+    attr_reader :source_lines
+
+    # Parses the specified Haml code into a {Document}.
+    #
+    # @param source [String] Haml code to parse
+    # @param options [Hash]
+    # @option options :file [String] file name of document that was parsed
+    # @raise [Haml::Parser::Error] if there was a problem parsing the document
+    def initialize(source, options)
+      @config = options[:config]
+      @file = options.fetch(:file, STRING_SOURCE)
+
+      process_source(source)
+    end
+
+    private
+
+    # @param source [String] Haml code to parse
+    # @raise [Haml::Parser::Error] if there was a problem parsing the document
+    def process_source(source)
+      @source = strip_frontmatter(source)
+      @source_lines = @source.split("\n")
+
+      @tree = process_tree(Haml::Parser.new(@source, Haml::Options.new).parse)
+    end
+
+    # Processes the {Haml::Parser::ParseNode} tree and returns a tree composed
+    # of friendlier {HamlLint::Tree::Node}s.
+    #
+    # @param original_tree [Haml::Parser::ParseNode]
+    # @return [Haml::Tree::Node]
+    def process_tree(original_tree)
+      # Remove the trailing empty HAML comment that the parser creates to signal
+      # the end of the HAML document
+      if Gem::Requirement.new('~> 4.0.0').satisfied_by?(Gem.loaded_specs['haml'].version)
+        original_tree.children.pop
+      end
+
+      @node_transformer = HamlLint::NodeTransformer.new(self)
+      convert_tree(original_tree)
+    end
+
+    # Converts a HAML parse tree to a tree of {HamlLint::Tree::Node} objects.
+    #
+    # This provides a cleaner interface with which the linters can interact with
+    # the parse tree.
+    #
+    # @param haml_node [Haml::Parser::ParseNode]
+    # @param parent [Haml::Tree::Node]
+    # @return [Haml::Tree::Node]
+    def convert_tree(haml_node, parent = nil)
+      new_node = @node_transformer.transform(haml_node)
+      new_node.parent = parent
+
+      new_node.children = haml_node.children.map do |child|
+        convert_tree(child, new_node)
+      end
+
+      new_node
+    end
+
+    # Removes YAML frontmatter
+    def strip_frontmatter(source)
+      if config['skip_frontmatter'] &&
+        source =~ /
+          # From the start of the string
+          \A
+          # First-capture match --- followed by optional whitespace up
+          # to a newline then 0 or more chars followed by an optional newline.
+          # This matches the --- and the contents of the frontmatter
+          (---\s*\n.*?\n?)
+          # From the start of the line
+          ^
+          # Second capture match --- or ... followed by optional whitespace
+          # and newline. This matches the closing --- for the frontmatter.
+          (---|\.\.\.)\s*$\n?/mx
+        source = $POSTMATCH
+      end
+
+      source
+    end
+  end
+end

data/lib/haml_lint/file_finder.rb

@@ -1,13 +1,15 @@
 require 'find'
 
 module HamlLint
-  # Finds HAML files that should be linted given a specified list of paths, glob
+  # Finds Haml files that should be linted given a specified list of paths, glob
   # patterns, and configuration.
   class FileFinder
     # List of extensions of files to include under a directory when a directory
     # is specified instead of a file.
     VALID_EXTENSIONS = %w[.haml]
 
+    # Create a file finder using the specified configuration.
+    #
     # @param config [HamlLint::Configuration]
     def initialize(config)
       @config = config
@@ -22,15 +24,18 @@ module HamlLint
     def find(patterns, excluded_patterns)
       extract_files_from(patterns).reject do |file|
         excluded_patterns.any? do |exclusion_glob|
-          ::File.fnmatch?(exclusion_glob, file,
-                          ::File::FNM_PATHNAME | # Wildcards don't match path separators
-                          ::File::FNM_DOTMATCH)  # `*` wildcard matches dotfiles
+          HamlLint::Utils.any_glob_matches?(exclusion_glob, file)
         end
       end
     end
 
     private
 
+    # Extract the list of matching files given the list of glob patterns, file
+    # paths, and directories.
+    #
+    # @param patterns [Array<String>]
+    # @return [Array<String>]
     def extract_files_from(patterns) # rubocop:disable MethodLength
       files = []
 
@@ -57,9 +62,13 @@ module HamlLint
         end
       end
 
-      files.uniq
+      files.uniq.sort
     end
 
+    # Whether the given file should be treated as a Haml file.
+    #
+    # @param file [String]
+    # @return [Boolean]
     def haml_file?(file)
       return false unless ::FileTest.file?(file)
 

data/lib/haml_lint/lint.rb

@@ -1,7 +1,20 @@
 module HamlLint
   # Contains information about a problem or issue with a HAML document.
   class Lint
-    attr_reader :filename, :line, :linter, :message, :severity
+    # @return [String] file path to which the lint applies
+    attr_reader :filename
+
+    # @return [String] line number of the file the lint corresponds to
+    attr_reader :line
+
+    # @return [SlimLint::Linter] linter that reported the lint
+    attr_reader :linter
+
+    # @return [String] error/warning message to display to user
+    attr_reader :message
+
+    # @return [Symbol] whether this lint is a warning or an error
+    attr_reader :severity
 
     # Creates a new lint.
     #
@@ -18,6 +31,9 @@ module HamlLint
       @severity = severity
     end
 
+    # Return whether this lint has a severity of error.
+    #
+    # @return [Boolean]
     def error?
       @severity == :error
     end

data/lib/haml_lint/linter/alt_text.rb

@@ -5,7 +5,7 @@ module HamlLint
 
     def visit_tag(node)
       if node.tag_name == 'img' && !node.has_hash_attribute?(:alt)
-        add_lint(node, '`img` tags must include alt text')
+        record_lint(node, '`img` tags must include alt text')
       end
     end
   end

data/lib/haml_lint/linter/class_attribute_with_static_value.rb

@@ -18,8 +18,8 @@ module HamlLint
     def visit_tag(node)
       return unless contains_class_attribute?(node.dynamic_attributes_sources)
 
-      add_lint(node, 'Avoid defining `class` in attributes hash ' \
-                     'for static class names')
+      record_lint(node, 'Avoid defining `class` in attributes hash ' \
+                        'for static class names')
     end
 
     private

data/lib/haml_lint/linter/classes_before_ids.rb

@@ -17,8 +17,8 @@ module HamlLint
         next unless components[index].start_with?('.') &&
                     components[index - 1].start_with?('#')
 
-        add_lint(node, 'Classes should be listed before IDs '\
-                       "(#{components[index]} should precede #{components[index - 1]})")
+        record_lint(node, 'Classes should be listed before IDs '\
+                          "(#{components[index]} should precede #{components[index - 1]})")
         break
       end
     end

data/lib/haml_lint/linter/consecutive_comments.rb

@@ -3,17 +3,15 @@ module HamlLint
   class Linter::ConsecutiveComments < Linter
     include LinterRegistry
 
-    MIN_CONSECUTIVE = 2
     COMMENT_DETECTOR = ->(child) { child.type == :haml_comment }
 
     def visit_root(node)
-      HamlLint::Utils.find_consecutive(
+      HamlLint::Utils.for_consecutive_items(
         node.children,
-        MIN_CONSECUTIVE,
         COMMENT_DETECTOR,
       ) do |group|
-        add_lint(group.first,
-                 "#{group.count} consecutive comments can be merged into one")
+        record_lint(group.first,
+                    "#{group.count} consecutive comments can be merged into one")
       end
     end
   end

data/lib/haml_lint/linter/consecutive_silent_scripts.rb

@@ -9,14 +9,14 @@ module HamlLint
     end
 
     def visit_root(node)
-      HamlLint::Utils.find_consecutive(
+      HamlLint::Utils.for_consecutive_items(
         node.children,
-        config['max_consecutive'] + 1,
         SILENT_SCRIPT_DETECTOR,
+        config['max_consecutive'] + 1,
       ) do |group|
-        add_lint(group.first,
-                 "#{group.count} consecutive Ruby scripts can be merged into " \
-                 'a single `:ruby` filter')
+        record_lint(group.first,
+                    "#{group.count} consecutive Ruby scripts can be merged " \
+                    'into a single `:ruby` filter')
       end
     end
   end

data/lib/haml_lint/linter/empty_script.rb

@@ -6,7 +6,7 @@ module HamlLint
     def visit_silent_script(node)
       return unless node.script =~ /\A\s*\Z/
 
-      add_lint(node, 'Empty script should be removed')
+      record_lint(node, 'Empty script should be removed')
     end
   end
 end

data/lib/haml_lint/linter/html_attributes.rb

@@ -7,8 +7,8 @@ module HamlLint
     def visit_tag(node)
       return unless node.html_attributes?
 
-      add_lint(node, "Prefer the hash attributes syntax (%tag{ lang: 'en' }) over " \
-                     'HTML attributes syntax (%tag(lang=en))')
+      record_lint(node, "Prefer the hash attributes syntax (%tag{ lang: 'en' }) " \
+                        'over HTML attributes syntax (%tag(lang=en))')
     end
   end
 end

data/lib/haml_lint/linter/implicit_div.rb

@@ -12,9 +12,9 @@ module HamlLint
       tag = node.source_code[/\s*([^\s={\(\[]+)/, 1]
       return unless tag.start_with?('%div')
 
-      add_lint(node,
-               "`#{tag}` can be written as `#{node.static_attributes_source}` " \
-               'since `%div` is implicit')
+      record_lint(node,
+                  "`#{tag}` can be written as `#{node.static_attributes_source}` " \
+                  'since `%div` is implicit')
     end
   end
 end

data/lib/haml_lint/linter/leading_comment_space.rb

@@ -8,7 +8,7 @@ module HamlLint
       # or starts with a space
       return if node.text.match(/\A(\s*|\s+\S.*)$/)
 
-      add_lint(node, 'Comment should have a space after the `#`')
+      record_lint(node, 'Comment should have a space after the `#`')
     end
   end
 end

data/lib/haml_lint/linter/line_length.rb

@@ -9,10 +9,10 @@ module HamlLint
       max_length = config['max']
       dummy_node = Struct.new(:line)
 
-      parser.lines.each_with_index do |line, index|
+      document.source_lines.each_with_index do |line, index|
         next if line.length <= max_length
 
-        add_lint(dummy_node.new(index + 1), format(MSG, line.length, max_length))
+        record_lint(dummy_node.new(index + 1), format(MSG, line.length, max_length))
       end
     end
   end