haml_lint 0.13.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 343fc1d49926d0ac21d87fbfc26b93c518d690fc
+  data.tar.gz: 79d58c8fe3e0ded6c8cde5dee115276d84720fc1
+SHA512:
+  metadata.gz: 26259ff8ae9e582436736b4830a90c1256259a32d9d36372ec9dc8e823582c1cb4682bf2edb38c5db78b1d325c1d2baadd45f05fa8a1a3e6153aaa610bd38201
+  data.tar.gz: c30b1bcc9d65705bc944bd90e6743e2f26e35ebcb45df0158ad8db7702a7b03e7f94fe212265d91c88d780bbd112239bf88679f3e1e7614c585447f46d626468

data/bin/haml-lint

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+
+require 'haml_lint'
+require 'haml_lint/cli'
+
+logger = HamlLint::Logger.new(STDOUT)
+exit HamlLint::CLI.new(logger).run(ARGV)

data/config/default.yml

@@ -0,0 +1,91 @@
+# Default application configuration that all configurations inherit from.
+#
+# This is an opinionated list of which hooks are valuable to run and what their
+# out of the box settings should be.
+
+# Whether to ignore frontmatter at the beginning of HAML documents for
+# frameworks such as Jekyll/Middleman
+skip_frontmatter: false
+
+linters:
+  AltText:
+    enabled: false
+
+  ClassAttributeWithStaticValue:
+    enabled: true
+
+  ClassesBeforeIds:
+    enabled: true
+
+  ConsecutiveComments:
+    enabled: true
+
+  ConsecutiveSilentScripts:
+    enabled: true
+    max_consecutive: 2
+
+  EmptyScript:
+    enabled: true
+
+  HtmlAttributes:
+    enabled: true
+
+  ImplicitDiv:
+    enabled: true
+
+  LeadingCommentSpace:
+    enabled: true
+
+  LineLength:
+    enabled: true
+    max: 80
+
+  MultilinePipe:
+    enabled: true
+
+  MultilineScript:
+    enabled: true
+
+  ObjectReferenceAttributes:
+    enabled: true
+
+  RuboCop:
+    enabled: true
+    # These cops are incredibly noisy when it comes to HAML templates, so we
+    # ignore them.
+    ignored_cops:
+      - Lint/BlockAlignment
+      - Lint/EndAlignment
+      - Lint/Void
+      - Metrics/LineLength
+      - Style/AlignParameters
+      - Style/BlockNesting
+      - Style/FileName
+      - Style/IfUnlessModifier
+      - Style/IndentationWidth
+      - Style/Next
+      - Style/TrailingBlankLines
+      - Style/TrailingWhitespace
+      - Style/WhileUntilModifier
+
+  RubyComments:
+    enabled: true
+
+  SpaceBeforeScript:
+    enabled: true
+
+  SpaceInsideHashAttributes:
+    enabled: true
+    style: space
+
+  TagName:
+    enabled: true
+
+  TrailingWhitespace:
+    enabled: true
+
+  UnnecessaryInterpolation:
+    enabled: true
+
+  UnnecessaryStringOutput:
+    enabled: true

data/lib/haml_lint/cli.rb

@@ -0,0 +1,122 @@
+require 'haml_lint/options'
+
+require 'sysexits'
+
+module HamlLint
+  # Command line application interface.
+  class CLI
+    attr_accessor :options
+
+    # @param logger [HamlLint::Logger]
+    def initialize(logger)
+      @log = logger
+    end
+
+    # Parses the given command-line arguments and executes appropriate logic
+    # based on those arguments.
+    #
+    # @param args [Array<String>] command line arguments
+    # @return [Fixnum] exit status returned by the application
+    def run(args)
+      options = HamlLint::Options.new.parse(args)
+      act_on_options(options)
+    rescue => ex
+      handle_exception(ex)
+    end
+
+    private
+
+    attr_reader :log
+
+    def act_on_options(options)
+      log.color_enabled = options.fetch(:color, log.tty?)
+
+      if options[:help]
+        print_help(options)
+        Sysexits::EX_OK
+      elsif options[:version]
+        print_version
+        Sysexits::EX_OK
+      elsif options[:show_linters]
+        print_available_linters
+        Sysexits::EX_OK
+      elsif options[:show_reporters]
+        print_available_reporters
+        Sysexits::EX_OK
+      else
+        scan_for_lints(options)
+      end
+    end
+
+    def handle_exception(ex)
+      case ex
+      when HamlLint::Exceptions::ConfigurationError
+        log.error ex.message
+        Sysexits::EX_CONFIG
+      when HamlLint::Exceptions::InvalidCLIOption
+        log.error ex.message
+        log.log "Run `#{APP_NAME}` --help for usage documentation"
+        Sysexits::EX_USAGE
+      when HamlLint::Exceptions::InvalidFilePath
+        log.error ex.message
+        Sysexits::EX_NOINPUT
+      when HamlLint::Exceptions::NoLintersError
+        log.error ex.message
+        Sysexits::EX_NOINPUT
+      else
+        print_unexpected_exception(ex)
+        Sysexits::EX_SOFTWARE
+      end
+    end
+
+    def scan_for_lints(options)
+      report = Runner.new.run(options)
+      print_report(report, options)
+      report.failed? ? Sysexits::EX_DATAERR : Sysexits::EX_OK
+    end
+
+    def print_report(report, options)
+      reporter = options.fetch(:reporter, Reporter::DefaultReporter).new(log, report)
+      reporter.report_lints
+    end
+
+    def print_available_linters
+      log.info 'Available linters:'
+
+      linter_names = LinterRegistry.linters.map do |linter|
+        linter.name.split('::').last
+      end
+
+      linter_names.sort.each do |linter_name|
+        log.log " - #{linter_name}"
+      end
+    end
+
+    def print_available_reporters
+      log.info 'Available reporters:'
+
+      reporter_names = Reporter.descendants.map do |reporter|
+        reporter.name.split('::').last.sub(/Reporter$/, '').downcase
+      end
+
+      reporter_names.sort.each do |reporter_name|
+        log.log " - #{reporter_name}"
+      end
+    end
+
+    def print_help(options)
+      log.log options[:help]
+    end
+
+    def print_version
+      log.log "#{APP_NAME} #{HamlLint::VERSION}"
+    end
+
+    def print_unexpected_exception(ex)
+      log.bold_error ex.message
+      log.error ex.backtrace.join("\n")
+      log.warning 'Report this bug at ', false
+      log.info HamlLint::BUG_REPORT_URL
+    end
+  end
+end

data/lib/haml_lint/configuration.rb

@@ -0,0 +1,97 @@
+module HamlLint
+  # Stores configuration for haml-lint.
+  class Configuration
+    attr_reader :hash
+
+    # Creates a configuration from the given options hash.
+    #
+    # @param options [Hash]
+    def initialize(options)
+      @hash = options
+      validate
+    end
+
+    # Compares this configuration with another.
+    #
+    # @param other [HamlLint::Configuration]
+    # @return [true,false] whether the given configuration is equivalent
+    def ==(other)
+      super || @hash == other.hash
+    end
+    alias_method :eql?, :==
+
+    # Returns a non-modifiable configuration for the specified linter.
+    #
+    # @param linter [HamlLint::Linter,Class]
+    def for_linter(linter)
+      linter_name =
+        case linter
+        when Class
+          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
+    end
+
+    # Merges the given configuration with this one, returning a new
+    # {Configuration}. The provided configuration will either add to or replace
+    # any options defined in this configuration.
+    #
+    # @param config [HamlLint::Configuration]
+    def merge(config)
+      self.class.new(smart_merge(@hash, config.hash))
+    end
+
+    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
+
+    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
+          new
+        end
+      end
+    end
+
+    def ensure_linter_section_exists(hash)
+      hash['linters'] ||= {}
+      hash['linters']['ALL'] ||= {}
+    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
+      end
+    end
+  end
+end

data/lib/haml_lint/configuration_loader.rb

@@ -0,0 +1,68 @@
+require 'pathname'
+require 'yaml'
+
+module HamlLint
+  # Manages configuration file loading.
+  class ConfigurationLoader
+    DEFAULT_CONFIG_PATH = File.join(HAML_LINT_HOME, 'config', 'default.yml')
+    CONFIG_FILE_NAME = '.haml-lint.yml'
+
+    class << self
+      def load_applicable_config
+        directory = File.expand_path(Dir.pwd)
+        config_file = possible_config_files(directory).find(&:file?)
+
+        if config_file
+          load_file(config_file.to_path)
+        else
+          default_configuration
+        end
+      end
+
+      def default_configuration
+        @default_config ||= load_from_file(DEFAULT_CONFIG_PATH)
+      end
+
+      # Loads a configuration, ensuring it extends the default configuration.
+      def load_file(file)
+        config = load_from_file(file)
+
+        default_configuration.merge(config)
+      rescue => error
+        raise HamlLint::Exceptions::ConfigurationError,
+              "Unable to load configuration from '#{file}': #{error}",
+              error.backtrace
+      end
+
+      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
+
+      def load_from_file(file)
+        hash =
+          if yaml = YAML.load_file(file)
+            yaml.to_hash
+          else
+            {}
+          end
+
+        HamlLint::Configuration.new(hash)
+      end
+
+      def possible_config_files(directory)
+        files = Pathname.new(directory)
+                        .enum_for(:ascend)
+                        .map { |path| path + CONFIG_FILE_NAME }
+        files << Pathname.new(CONFIG_FILE_NAME)
+      end
+    end
+  end
+end

data/lib/haml_lint/constants.rb

@@ -0,0 +1,8 @@
+# Global application constants.
+module HamlLint
+  HAML_LINT_HOME = File.expand_path(File.join(File.dirname(__FILE__), '..', '..'))
+  APP_NAME = 'haml-lint'
+
+  REPO_URL = 'https://github.com/brigade/haml-lint'
+  BUG_REPORT_URL = "#{REPO_URL}/issues"
+end

data/lib/haml_lint/exceptions.rb

@@ -0,0 +1,15 @@
+# Collection of exceptions that can be raised by the HAML Lint application.
+module HamlLint::Exceptions
+  # Raised when a {Configuration} could not be loaded from a file.
+  class ConfigurationError < StandardError; end
+
+  # Raised when invalid/incompatible command line options are provided.
+  class InvalidCLIOption < StandardError; end
+
+  # Raised when an invalid file path is specified
+  class InvalidFilePath < StandardError; end
+
+  # Raised when attempting to execute `Runner` with options that would result in
+  # no linters being enabled.
+  class NoLintersError < StandardError; end
+end

data/lib/haml_lint/file_finder.rb

@@ -0,0 +1,69 @@
+require 'find'
+
+module HamlLint
+  # 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]
+
+    # @param config [HamlLint::Configuration]
+    def initialize(config)
+      @config = config
+    end
+
+    # Return list of files to lint given the specified set of paths and glob
+    # patterns.
+    # @param patterns [Array<String>]
+    # @param excluded_patterns [Array<String>]
+    # @raise [HamlLint::Exceptions::InvalidFilePath]
+    # @return [Array<String>] list of actual files
+    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
+        end
+      end
+    end
+
+    private
+
+    def extract_files_from(patterns) # rubocop:disable MethodLength
+      files = []
+
+      patterns.each do |pattern|
+        if File.file?(pattern)
+          files << pattern
+        else
+          begin
+            ::Find.find(pattern) do |file|
+              files << file if haml_file?(file)
+            end
+          rescue ::Errno::ENOENT
+            # File didn't exist; it might be a file glob pattern
+            matches = ::Dir.glob(pattern)
+            if matches.any?
+              files += matches
+            else
+              # One of the paths specified does not exist; raise a more
+              # descriptive exception so we know which one
+              raise HamlLint::Exceptions::InvalidFilePath,
+                    "File path '#{pattern}' does not exist"
+            end
+          end
+        end
+      end
+
+      files.uniq
+    end
+
+    def haml_file?(file)
+      return false unless ::FileTest.file?(file)
+
+      VALID_EXTENSIONS.include?(::File.extname(file))
+    end
+  end
+end

data/lib/haml_lint/haml_visitor.rb

@@ -0,0 +1,36 @@
+module HamlLint
+  # Provides an interface which when included allows a class to visit nodes in
+  # the parse tree of a HAML document.
+  module HamlVisitor
+    def visit(node)
+      # Keep track of whether this block was consumed by the visitor. This
+      # allows us to visit all nodes by default, but can override the behavior
+      # by specifying `yield false` in a visit method, indicating that no
+      # further visiting should occur for the current node's children.
+      block_called = false
+
+      block = ->(descend = :children) do
+        block_called = true
+        visit_children(node) if descend == :children
+      end
+
+      method = "visit_#{node_name(node)}"
+      send(method, node, &block) if respond_to?(method, true)
+
+      # Visit all children by default unless the block was invoked (indicating
+      # the user intends to not recurse further, or wanted full control over
+      # when the children were visited).
+      visit_children(node) unless block_called
+    end
+
+    def visit_children(parent)
+      parent.children.each { |node| visit(node) }
+    end
+
+    private
+
+    def node_name(node)
+      node.type
+    end
+  end
+end

data/lib/haml_lint/lint.rb

@@ -0,0 +1,25 @@
+module HamlLint
+  # Contains information about a problem or issue with a HAML document.
+  class Lint
+    attr_reader :filename, :line, :linter, :message, :severity
+
+    # Creates a new lint.
+    #
+    # @param linter [HamlLint::Linter]
+    # @param filename [String]
+    # @param line [Fixnum]
+    # @param message [String]
+    # @param severity [Symbol]
+    def initialize(linter, filename, line, message, severity = :warning)
+      @linter   = linter
+      @filename = filename
+      @line     = line || 0
+      @message  = message
+      @severity = severity
+    end
+
+    def error?
+      @severity == :error
+    end
+  end
+end

data/lib/haml_lint/linter/alt_text.rb

@@ -0,0 +1,12 @@
+module HamlLint
+  # Checks for missing `alt` attributes on `img` tags.
+  class Linter::AltText < Linter
+    include LinterRegistry
+
+    def visit_tag(node)
+      if node.tag_name == 'img' && !node.has_hash_attribute?(:alt)
+        add_lint(node, '`img` tags must include alt text')
+      end
+    end
+  end
+end

data/lib/haml_lint/linter/class_attribute_with_static_value.rb

@@ -0,0 +1,51 @@
+module HamlLint
+  # Checks for class attributes defined in tag attribute hash with static
+  # values.
+  #
+  # For example, it will prefer this:
+  #
+  #   %tag.class-name
+  #
+  # ...over:
+  #
+  #   %tag{ class: 'class-name' }
+  class Linter::ClassAttributeWithStaticValue < Linter
+    include LinterRegistry
+
+    STATIC_TYPES = [:str, :sym]
+    STATIC_CLASSES = [String, Symbol]
+
+    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')
+    end
+
+    private
+
+    def contains_class_attribute?(attributes_sources)
+      attributes_sources.each do |code|
+        begin
+          ast_root = parse_ruby(code.start_with?('{') ? code : "{#{code}}")
+        rescue ::Parser::SyntaxError
+          next # RuboCop linter will report syntax errors
+        end
+
+        ast_root.children.each do |pair|
+          return true if static_class_attribute_value?(pair)
+        end
+      end
+
+      false
+    end
+
+    def static_class_attribute_value?(pair)
+      key, value = pair.children
+
+      STATIC_TYPES.include?(key.type) &&
+        key.children.first.to_sym == :class &&
+        STATIC_CLASSES.include?(value.children.first.class)
+    end
+  end
+end

data/lib/haml_lint/linter/classes_before_ids.rb

@@ -0,0 +1,26 @@
+module HamlLint
+  # Checks that classes are listed before IDs in tags.
+  class Linter::ClassesBeforeIds < Linter
+    include LinterRegistry
+
+    # Map of prefixes to the type of tag component
+    TYPES_BY_PREFIX = {
+      '.' => :class,
+      '#' => :id,
+    }
+
+    def visit_tag(node)
+      # Convert ".class#id" into [.class, #id] (preserving order)
+      components = node.static_attributes_source.scan(/[.#][^.#]+/)
+
+      (1...components.count).each do |index|
+        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]})")
+        break
+      end
+    end
+  end
+end

data/lib/haml_lint/linter/consecutive_comments.rb

@@ -0,0 +1,20 @@
+module HamlLint
+  # Checks for multiple lines of code comments that can be condensed.
+  class Linter::ConsecutiveComments < Linter
+    include LinterRegistry
+
+    MIN_CONSECUTIVE = 2
+    COMMENT_DETECTOR = ->(child) { child.type == :haml_comment }
+
+    def visit_root(node)
+      HamlLint::Utils.find_consecutive(
+        node.children,
+        MIN_CONSECUTIVE,
+        COMMENT_DETECTOR,
+      ) do |group|
+        add_lint(group.first,
+                 "#{group.count} consecutive comments can be merged into one")
+      end
+    end
+  end
+end

data/lib/haml_lint/linter/consecutive_silent_scripts.rb

@@ -0,0 +1,23 @@
+module HamlLint
+  # Checks for multiple consecutive silent script markers that could be
+  # condensed into a :ruby filter block.
+  class Linter::ConsecutiveSilentScripts < Linter
+    include LinterRegistry
+
+    SILENT_SCRIPT_DETECTOR = ->(child) do
+      child.type == :silent_script && child.children.empty?
+    end
+
+    def visit_root(node)
+      HamlLint::Utils.find_consecutive(
+        node.children,
+        config['max_consecutive'] + 1,
+        SILENT_SCRIPT_DETECTOR,
+      ) do |group|
+        add_lint(group.first,
+                 "#{group.count} consecutive Ruby scripts can be merged into " \
+                 'a single `:ruby` filter')
+      end
+    end
+  end
+end