haml_lint 0.13.0

data/lib/haml_lint/logger.rb

@@ -0,0 +1,107 @@
+module HamlLint
+  # Encapsulates all communication to an output source.
+  class Logger
+    # Whether colored output via ANSI escape sequences is enabled.
+    # @return [true,false]
+    attr_accessor :color_enabled
+
+    # Creates a logger which outputs nothing.
+    # @return [HamlLint::Logger]
+    def self.silent
+      new(File.open('/dev/null', 'w'))
+    end
+
+    # Creates a new {HamlLint::Logger} instance.
+    #
+    # @param out [IO] the output destination.
+    def initialize(out)
+      @out = out
+    end
+
+    # Print the specified output.
+    #
+    # @param output [String] the output to send
+    # @param newline [true,false] whether to append a newline
+    # @return [nil]
+    def log(output, newline = true)
+      @out.print(output)
+      @out.print("\n") if newline
+    end
+
+    # Print the specified output in bold face.
+    # If output destination is not a TTY, behaves the same as {#log}.
+    #
+    # @param args [Array<String>]
+    # @return [nil]
+    def bold(*args)
+      color('1', *args)
+    end
+
+    # Print the specified output in a color indicative of error.
+    # If output destination is not a TTY, behaves the same as {#log}.
+    #
+    # @param args [Array<String>]
+    # @return [nil]
+    def error(*args)
+      color(31, *args)
+    end
+
+    # Print the specified output in a bold face and color indicative of error.
+    # If output destination is not a TTY, behaves the same as {#log}.
+    #
+    # @param args [Array<String>]
+    # @return [nil]
+    def bold_error(*args)
+      color('1;31', *args)
+    end
+
+    # Print the specified output in a color indicative of success.
+    # If output destination is not a TTY, behaves the same as {#log}.
+    #
+    # @param args [Array<String>]
+    # @return [nil]
+    def success(*args)
+      color(32, *args)
+    end
+
+    # Print the specified output in a color indicative of a warning.
+    # If output destination is not a TTY, behaves the same as {#log}.
+    #
+    # @param args [Array<String>]
+    # @return [nil]
+    def warning(*args)
+      color(33, *args)
+    end
+
+    # Print specified output in bold face in a color indicative of a warning.
+    # If output destination is not a TTY, behaves the same as {#log}.
+    #
+    # @param args [Array<String>]
+    # @return [nil]
+    def bold_warning(*args)
+      color('1;33', *args)
+    end
+
+    # Print the specified output in a color indicating information.
+    # If output destination is not a TTY, behaves the same as {#log}.
+    #
+    # @param args [Array<String>]
+    # @return [nil]
+    def info(*args)
+      color(36, *args)
+    end
+
+    # Whether this logger is outputting to a TTY.
+    #
+    # @return [true,false]
+    def tty?
+      @out.respond_to?(:tty?) && @out.tty?
+    end
+
+    private
+
+    def color(code, output, newline = true)
+      log(color_enabled ? "\033[#{code}m#{output}\033[0m" : output, newline)
+    end
+  end
+end

data/lib/haml_lint/node_transformer.rb

@@ -0,0 +1,28 @@
+module HamlLint
+  # Responsible for transforming {Haml::Parser::ParseNode} objects into
+  # corresponding {HamlLint::Tree::Node} objects.
+  #
+  # The parse tree generated by HAML has a number of strange cases where certain
+  # types of nodes are created that don't necessarily correspond to what one
+  # would expect. This class is intended to isolate and handle these cases so
+  # that linters don't have to deal with them.
+  class NodeTransformer
+    # Creates a node transformer for the given parser context.
+    #
+    # @param parser [HamlLint::Parser]
+    def initialize(parser)
+      @parser = parser
+    end
+
+    # Transforms the given {Haml::Parser::ParseNode} into its corresponding
+    # {HamlLint::Tree::Node}.
+    def transform(haml_node)
+      node_class = "#{HamlLint::Utils.camel_case(haml_node.type.to_s)}Node"
+
+      HamlLint::Tree.const_get(node_class).new(@parser, haml_node)
+    rescue NameError
+      # TODO: Wrap in parser error?
+      raise
+    end
+  end
+end

data/lib/haml_lint/options.rb

@@ -0,0 +1,89 @@
+require 'optparse'
+
+module HamlLint
+  # Handles option parsing for the command line application.
+  class Options
+    # Parses command line options into an options hash.
+    #
+    # @param args [Array<String>] arguments passed via the command line
+    # @return [Hash] parsed options
+    def parse(args)
+      @options = {}
+
+      OptionParser.new do |parser|
+        parser.banner = "Usage: #{APP_NAME} [options] [file1, file2, ...]"
+
+        add_linter_options parser
+        add_file_options parser
+        add_info_options parser
+      end.parse!(args)
+
+      # Any remaining arguments are assumed to be files
+      @options[:files] = args
+
+      @options
+    rescue OptionParser::InvalidOption => ex
+      raise Exceptions::InvalidCLIOption,
+            ex.message,
+            ex.backtrace
+    end
+
+    private
+
+    def add_linter_options(parser)
+      parser.on('-e', '--exclude file,...', Array,
+                'List of file names to exclude') do |files|
+        @options[:excluded_files] = files
+      end
+
+      parser.on('-i', '--include-linter linter,...', Array,
+                'Specify which linters you want to run') do |linters|
+        @options[:included_linters] = linters
+      end
+
+      parser.on('-x', '--exclude-linter linter,...', Array,
+                "Specify which linters you don't want to run") do |linters|
+        @options[:excluded_linters] = linters
+      end
+
+      parser.on('-r', '--reporter reporter', String,
+                'Specify which reporter you want to use to generate the output') do |reporter|
+        @options[:reporter] = HamlLint::Reporter.const_get("#{reporter.capitalize}Reporter")
+      end
+    end
+
+    def add_file_options(parser)
+      parser.on('-c', '--config config-file', String,
+                'Specify which configuration file you want to use') do |conf_file|
+        @options[:config_file] = conf_file
+      end
+
+      parser.on('-e', '--exclude file,...', Array,
+                'List of file names to exclude') do |files|
+        @options[:excluded_files] = files
+      end
+    end
+
+    def add_info_options(parser)
+      parser.on('--show-linters', 'Display available linters') do
+        @options[:show_linters] = true
+      end
+
+      parser.on('--show-reporters', 'Display available reporters') do
+        @options[:show_reporters] = true
+      end
+
+      parser.on('--[no-]color', 'Force output to be colorized') do |color|
+        @options[:color] = color
+      end
+
+      parser.on_tail('-h', '--help', 'Display help documentation') do
+        @options[:help] = parser.help
+      end
+
+      parser.on_tail('-v', '--version', 'Display version') do
+        @options[:version] = true
+      end
+    end
+  end
+end

data/lib/haml_lint/parser.rb

@@ -0,0 +1,87 @@
+require 'haml'
+
+module HamlLint
+  # Parses a HAML document for inspection by linters.
+  class Parser
+    attr_reader :contents, :filename, :lines, :tree
+
+    # Creates a parser containing the parse tree of a HAML document.
+    #
+    # @param haml_or_filename [String]
+    # @param options [Hash]
+    # @option options [true,false] 'skip_frontmatter' Whether to skip
+    #   frontmatter included by frameworks such as Middleman or Jekyll
+    def initialize(haml_or_filename, options = {})
+      if File.exist?(haml_or_filename)
+        build_from_file(haml_or_filename)
+      else
+        build_from_string(haml_or_filename)
+      end
+
+      process_options(options)
+
+      build_parse_tree
+    end
+
+    private
+
+    # @param path [String]
+    def build_from_file(path)
+      @filename = path
+      @contents = File.read(path)
+    end
+
+    # @param haml [String]
+    def build_from_string(haml)
+      @contents = haml
+    end
+
+    def build_parse_tree
+      original_tree = Haml::Parser.new(@contents, Haml::Options.new).parse
+
+      # 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)
+      @tree = convert_tree(original_tree)
+    end
+
+    def process_options(options)
+      if options['skip_frontmatter'] &&
+        @contents =~ /
+          # 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
+        @contents = $POSTMATCH
+      end
+
+      @lines = @contents.split("\n")
+    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.
+    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
+  end
+end

data/lib/haml_lint/rake_task.rb

@@ -0,0 +1,107 @@
+require 'rake'
+require 'rake/tasklib'
+
+module HamlLint
+  # Rake task interface for haml-lint command line interface.
+  #
+  # @example
+  #   # Add the following to your Rakefile...
+  #   require 'haml_lint/rake_task'
+  #
+  #   HamlLint::RakeTask.new do |t|
+  #     t.config = 'path/to/custom/haml-lint.yml'
+  #     t.files = %w[app/views/**/*.haml custom/*.haml]
+  #     t.quiet = true # Don't display output from haml-lint
+  #   end
+  #
+  #   # ...and then execute from the command line:
+  #   rake haml_lint
+  #
+  # You can also specify the list of files as explicit task arguments:
+  #
+  # @example
+  #   # Add the following to your Rakefile...
+  #   require 'haml_lint/rake_task'
+  #
+  #   HamlLint::RakeTask.new
+  #
+  #   # ...and then execute from the command line (single quotes prevent shell
+  #   # glob expansion and allow us to have a space after commas):
+  #   rake 'haml_lint[app/views/**/*.haml, other_files/**/*.haml]'
+  #
+  class RakeTask < Rake::TaskLib
+    # Name of the task.
+    # @return [String]
+    attr_accessor :name
+
+    # Configuration file to use.
+    # @return [String]
+    attr_accessor :config
+
+    # List of files to lint (can contain shell globs).
+    #
+    # Note that this will be ignored if you explicitly pass a list of files as
+    # task arguments via the command line or a task definition.
+    # @return [Array<String>]
+    attr_accessor :files
+
+    # Whether output from haml-lint should not be displayed to the standard out
+    # stream.
+    # @return [true,false]
+    attr_accessor :quiet
+
+    # Create the task so it exists in the current namespace.
+    def initialize(name = :haml_lint)
+      @name = name
+      @files = ['.'] # Search for everything under current directory by default
+      @quiet = false
+
+      yield self if block_given?
+
+      define
+    end
+
+    private
+
+    def define
+      desc default_description unless ::Rake.application.last_description
+
+      task(name, [:files]) do |_task, task_args|
+        # Lazy-load so task doesn't affect Rakefile load time
+        require 'haml_lint'
+        require 'haml_lint/cli'
+
+        run_cli(task_args)
+      end
+    end
+
+    def run_cli(task_args)
+      cli_args = ['--config', config] if config
+
+      logger = quiet ? HamlLint::Logger.silent : HamlLint::Logger.new(STDOUT)
+      result = HamlLint::CLI.new(logger).run(Array(cli_args) + files_to_lint(task_args))
+
+      fail "haml-lint failed with exit code #{result}" unless result == 0
+    end
+
+    def files_to_lint(task_args)
+      # Note: we're abusing Rake's argument handling a bit here. We call the
+      # first argument `files` but it's actually only the first file--we pull
+      # the rest out of the `extras` from the task arguments. This is so we
+      # can specify an arbitrary list of files separated by commas on the
+      # command line or in a custom task definition.
+      explicit_files = Array(task_args[:files]) + Array(task_args.extras)
+
+      explicit_files.any? ? explicit_files : files
+    end
+
+    # Friendly description that shows the full command that will be executed.
+    def default_description
+      description = 'Run `haml-lint'
+      description += " --config #{config}" if config
+      description += " #{files.join(' ')}" if files.any?
+      description += ' [files...]`'
+      description
+    end
+  end
+end

data/lib/haml_lint/report.rb

@@ -0,0 +1,16 @@
+module HamlLint
+  # Contains information about all lints detected during a scan.
+  class Report
+    attr_accessor :lints
+    attr_reader :files
+
+    def initialize(lints, files)
+      @lints = lints.sort_by { |l| [l.filename, l.line] }
+      @files = files
+    end
+
+    def failed?
+      @lints.any?
+    end
+  end
+end

data/lib/haml_lint/reporter/default_reporter.rb

@@ -0,0 +1,39 @@
+module HamlLint
+  # Outputs lints in a simple format with the filename, line number, and lint
+  # message.
+  class Reporter::DefaultReporter < Reporter
+    def report_lints
+      sorted_lints = lints.sort_by { |l| [l.filename, l.line] }
+
+      sorted_lints.each do |lint|
+        print_location(lint)
+        print_type(lint)
+        print_message(lint)
+      end
+    end
+
+    private
+
+    def print_location(lint)
+      log.info lint.filename, false
+      log.log ':', false
+      log.bold lint.line, false
+    end
+
+    def print_type(lint)
+      if lint.error?
+        log.error ' [E] ', false
+      else
+        log.warning ' [W] ', false
+      end
+    end
+
+    def print_message(lint)
+      if lint.linter
+        log.success("#{lint.linter.name}: ", false)
+      end
+
+      log.log lint.message
+    end
+  end
+end

data/lib/haml_lint/reporter/json_reporter.rb

@@ -0,0 +1,44 @@
+module HamlLint
+  # Outputs report as a JSON document.
+  class Reporter::JsonReporter < Reporter
+    def report_lints
+      grouped = lints.group_by(&:filename)
+
+      report = {
+        metadata: {
+          hamllint_version: VERSION,
+          ruby_engine:      RUBY_ENGINE,
+          ruby_patchlevel:  RUBY_PATCHLEVEL.to_s,
+          ruby_platform:    RUBY_PLATFORM,
+        },
+        files: grouped.map { |l| map_file(l) },
+        summary: {
+          offense_count: lints.length,
+          target_file_count: grouped.length,
+          inspected_file_count: files.length,
+        },
+      }
+
+      log.log report.to_json
+    end
+
+    private
+
+    def map_file(file)
+      {
+        path: file.first,
+        offenses: file.last.map { |o| map_offense(o) },
+      }
+    end
+
+    def map_offense(offense)
+      {
+        severity: offense.severity,
+        message: offense.message,
+        location: {
+          line: offense.line,
+        },
+      }
+    end
+  end
+end

data/lib/haml_lint/reporter.rb

@@ -0,0 +1,36 @@
+module HamlLint
+  # Abstract lint reporter. Subclass and override {#report_lints} to
+  # implement a custom lint reporter.
+  #
+  # @abstract
+  class Reporter
+    attr_reader :lints
+    attr_reader :files
+
+    # @param logger [HamlLint::Logger]
+    # @param report [HamlLint::Report]
+    def initialize(logger, report)
+      @log = logger
+      @lints = report.lints
+      @files = report.files
+    end
+
+    # Implemented by subclasses to display lints from a {HamlLint::Report}.
+    def report_lints
+      raise NotImplementedError
+    end
+
+    # Keep tracking all the descendants of this class for the list of available reporters
+    def self.descendants
+      @descendants ||= []
+    end
+
+    def self.inherited(descendant)
+      descendants << descendant
+    end
+
+    private
+
+    attr_reader :log
+  end
+end

data/lib/haml_lint/ruby_parser.rb

@@ -0,0 +1,29 @@
+require 'astrolabe/builder'
+require 'parser/current'
+
+module HamlLint
+  # Parser for the Ruby language.
+  #
+  # This provides a convenient wrapper around the `parser` gem and the
+  # `astrolabe` integration to go with it. It is intended to be used for linter
+  # checks that require deep inspection of Ruby code.
+  class RubyParser
+    # Creates a reusable parser.
+    def initialize
+      @builder = ::Astrolabe::Builder.new
+      @parser = ::Parser::CurrentRuby.new(@builder)
+    end
+
+    # Parse the given Ruby source into an abstract syntax tree.
+    #
+    # @param source [String] Ruby source code
+    # @return [Array] syntax tree in the form returned by Parser gem
+    def parse(source)
+      buffer = ::Parser::Source::Buffer.new('(string)')
+      buffer.source = source
+
+      @parser.reset
+      @parser.parse(buffer)
+    end
+  end
+end

data/lib/haml_lint/runner.rb

@@ -0,0 +1,76 @@
+module HamlLint
+  # Responsible for running the applicable linters against the desired files.
+  class Runner
+    # Make the list of applicable files available
+    attr_reader :files
+
+    # Runs the appropriate linters against the desired files given the specified
+    # options.
+    #
+    # @param options [Hash]
+    # @raise [HamlLint::Exceptions::NoLintersError] when no linters are enabled
+    # @return [HamlLint::Report] a summary of all lints found
+    def run(options = {})
+      config = load_applicable_config(options)
+      files = extract_applicable_files(options, config)
+      linters = extract_enabled_linters(config, options)
+
+      raise HamlLint::Exceptions::NoLintersError, 'No linters specified' if linters.empty?
+
+      @lints = []
+      files.each do |file|
+        find_lints(file, linters, config)
+      end
+
+      linters.each do |linter|
+        @lints += linter.lints
+      end
+
+      HamlLint::Report.new(@lints, files)
+    end
+
+    private
+
+    def load_applicable_config(options)
+      if options[:config_file]
+        HamlLint::ConfigurationLoader.load_file(options[:config_file])
+      else
+        HamlLint::ConfigurationLoader.load_applicable_config
+      end
+    end
+
+    def extract_enabled_linters(config, options)
+      included_linters = LinterRegistry
+        .extract_linters_from(options.fetch(:included_linters, []))
+
+      included_linters = LinterRegistry.linters if included_linters.empty?
+
+      excluded_linters = LinterRegistry
+        .extract_linters_from(options.fetch(:excluded_linters, []))
+
+      # After filtering out explicitly included/excluded linters, only include
+      # linters which are enabled in the configuration
+      (included_linters - excluded_linters).map do |linter_class|
+        linter_config = config.for_linter(linter_class)
+        linter_class.new(linter_config) if linter_config['enabled']
+      end.compact
+    end
+
+    def find_lints(file, linters, config)
+      parser = Parser.new(file, config.hash)
+
+      linters.each do |linter|
+        linter.run(parser)
+      end
+    rescue Haml::Error => ex
+      @lints << Lint.new(nil, file, ex.line, ex.to_s, :error)
+    end
+
+    def extract_applicable_files(options, config)
+      included_patterns = options[:files]
+      excluded_files = options.fetch(:excluded_files, [])
+
+      HamlLint::FileFinder.new(config).find(included_patterns, excluded_files)
+    end
+  end
+end