slim_lint 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: ea825ed5f8f37b9f5c0f65af4cce47ee9289227c
+  data.tar.gz: 31f794679bd7928f0e7990e3802319e2aeaa1764
+SHA512:
+  metadata.gz: 60c07b39dab5f98178fa7a01318e42c97e64676810309a03932b836fe1800bb9265203da373a601aa9882d53afc5b23d15c487efcab2d0a74871d7fcbe6f15b3
+  data.tar.gz: 8a65468ddb8de4b2834178f5e89ce90203281678d3d1cb2c0eeb42a22ffc6d6f10ef115ad65e7ab3d237043d2730f9ed4d5969add7f465becbd0ae99b485606a

data/bin/slim-lint

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

data/config/default.yml

@@ -0,0 +1,38 @@
+# 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 Slim documents for
+# frameworks such as Jekyll/Middleman
+skip_frontmatter: false
+
+linters:
+  ExplicitDiv:
+    enabled: true
+
+  LineLength:
+    enabled: true
+    max: 80
+
+  RuboCop:
+    enabled: true
+    # These cops are incredibly noisy since the Ruby we extract from Slim
+    # templates isn't well-formatted, 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
+
+  TrailingWhitespace:
+    enabled: true

data/lib/slim_lint/cli.rb

@@ -0,0 +1,122 @@
+require 'slim_lint/options'
+
+require 'sysexits'
+
+module SlimLint
+  # Command line application interface.
+  class CLI
+    attr_accessor :options
+
+    # @param logger [SlimLint::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 = SlimLint::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 SlimLint::Exceptions::ConfigurationError
+        log.error ex.message
+        Sysexits::EX_CONFIG
+      when SlimLint::Exceptions::InvalidCLIOption
+        log.error ex.message
+        log.log "Run `#{APP_NAME}` --help for usage documentation"
+        Sysexits::EX_USAGE
+      when SlimLint::Exceptions::InvalidFilePath
+        log.error ex.message
+        Sysexits::EX_NOINPUT
+      when SlimLint::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} #{SlimLint::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 SlimLint::BUG_REPORT_URL
+    end
+  end
+end

data/lib/slim_lint/configuration.rb

@@ -0,0 +1,101 @@
+module SlimLint
+  # Stores runtime configuration for the application.
+  class Configuration
+    attr_reader :hash
+
+    # Creates a configuration from the given options hash.
+    #
+    # @param options [Hash]
+    def initialize(options)
+      @hash = options
+      validate
+    end
+
+    # @param key [String]
+    # @return [Array,Hash,Number,String]
+    def [](key)
+      @hash[key]
+    end
+
+    # Compares this configuration with another.
+    #
+    # @param other [SlimLint::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 [SlimLint::Linter,Class]
+    def for_linter(linter)
+      linter_name =
+        case linter
+        when Class
+          linter.name.split('::').last
+        when SlimLint::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 [SlimLint::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 [SlimLint::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 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/slim_lint/configuration_loader.rb

@@ -0,0 +1,68 @@
+require 'pathname'
+require 'yaml'
+
+module SlimLint
+  # Manages configuration file loading.
+  class ConfigurationLoader
+    DEFAULT_CONFIG_PATH = File.join(SlimLint::HOME, 'config', 'default.yml')
+    CONFIG_FILE_NAME = '.slim-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 SlimLint::Exceptions::ConfigurationError,
+              "Unable to load configuration from '#{file}': #{error}",
+              error.backtrace
+      end
+
+      def load_hash(hash)
+        config = SlimLint::Configuration.new(hash)
+
+        default_configuration.merge(config)
+      rescue => error
+        raise SlimLint::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
+
+        SlimLint::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/slim_lint/constants.rb

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

data/lib/slim_lint/document.rb

@@ -0,0 +1,52 @@
+module SlimLint
+  # Represents a parsed Slim document and its associated metadata.
+  class Document
+    attr_reader :config, :file, :sexp, :source, :source_lines
+
+    # Parses the specified Slim code into a {Document}.
+    #
+    # @param source [String] Slim code to parse
+    # @param options [Hash]
+    # @option file [String] file name of document that was parsed
+    # @raise [Slim::Parser::Error] if there was a problem parsing the document
+    def initialize(source, options)
+      @config = options[:config]
+      @file = options.fetch(:file, '(string)')
+
+      process_source(source)
+    end
+
+    private
+
+    # @param source [String] Slim code to parse
+    # @raise [Slim::Parser::Error] if there was a problem parsing the document
+    def process_source(source)
+      @source = strip_frontmatter(source)
+      @source_lines = @source.split("\n")
+
+      @engine = SlimLint::Engine.new(file: @file)
+      @sexp = @engine.call(source)
+    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/slim_lint/engine.rb

@@ -0,0 +1,27 @@
+module SlimLint
+  # Temple engine used to generate a {Sexp} parse tree for use by linters.
+  #
+  # We omit a lot of the filters that are in {Slim::Engine} because they result
+  # in information potentially being removed from the parse tree (since some
+  # Sexp abstractions are optimized/removed or otherwise transformed). In order
+  # for linters to be useful, they need to operate on the original parse tree.
+  #
+  # The other key task this engine accomplishes is converting the Array-based
+  # S-expressions into {SlimLint::Sexp} objects, which have a number of helper
+  # methods that makes working with them easier. It also annotates these
+  # {SlimLint::Sexp} objects with line numbers so it's easy to cross reference
+  # with the original source code.
+  class Engine < Temple::Engine
+    filter :Encoding
+    filter :RemoveBOM
+
+    # Parse into S-expression using Slim parser
+    use Slim::Parser
+
+    # Converts Array-based S-expressions into SlimLint::Sexp objects
+    use SlimLint::Filters::SexpConverter
+
+    # Annotates Sexps with line numbers
+    use SlimLint::Filters::InjectLineNumbers
+  end
+end

data/lib/slim_lint/exceptions.rb

@@ -0,0 +1,15 @@
+# Collection of exceptions that can be raised by the HAML Lint application.
+module SlimLint::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/slim_lint/file_finder.rb

@@ -0,0 +1,69 @@
+require 'find'
+
+module SlimLint
+  # Finds Slim 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[.slim]
+
+    # @param config [SlimLint::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 [SlimLint::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 slim_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 SlimLint::Exceptions::InvalidFilePath,
+                    "File path '#{pattern}' does not exist"
+            end
+          end
+        end
+      end
+
+      files.uniq
+    end
+
+    def slim_file?(file)
+      return false unless ::FileTest.file?(file)
+
+      VALID_EXTENSIONS.include?(::File.extname(file))
+    end
+  end
+end

data/lib/slim_lint/filters/inject_line_numbers.rb

@@ -0,0 +1,35 @@
+module SlimLint::Filters
+  # Traverses a Temple S-expression (that has already been converted to
+  # {SlimLint::Sexp} instances) and annotates them with line numbers.
+  #
+  # This is a hack that allows us to access line information directly from the
+  # S-expressions, which makes a lot of other tasks easier.
+  class InjectLineNumbers < Temple::Filter
+    NEWLINE_SEXP = [:newline]
+
+    def call(sexp)
+      @line_number = 1
+      traverse(sexp)
+      sexp
+    end
+
+    private
+
+    # Traverses an {Sexp}, annotating it with line numbers by searching for
+    # :newline abstractions within it.
+    #
+    # @param sexp [SlimLint::Sexp]
+    def traverse(sexp)
+      sexp.line = @line_number
+
+      if sexp == NEWLINE_SEXP
+        @line_number += 1
+        return
+      end
+
+      sexp.each do |nested_sexp|
+        traverse(nested_sexp) if nested_sexp.is_a?(SlimLint::Sexp)
+      end
+    end
+  end
+end

data/lib/slim_lint/filters/sexp_converter.rb

@@ -0,0 +1,11 @@
+module SlimLint::Filters
+  # Converts a Temple S-expression comprised of {Array}s into {SlimLint::Sexp}s.
+  #
+  # These {SlimLint::Sexp}s include additional helpers that makes working with
+  # them more pleasant.
+  class SexpConverter < Temple::Filter
+    def call(array_sexp)
+      SlimLint::Sexp.new(array_sexp)
+    end
+  end
+end

data/lib/slim_lint/lint.rb

@@ -0,0 +1,25 @@
+module SlimLint
+  # 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 [SlimLint::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/slim_lint/linter/line_length.rb

@@ -0,0 +1,19 @@
+module SlimLint
+  # Checks for lines longer than a maximum number of columns.
+  class Linter::LineLength < Linter
+    include LinterRegistry
+
+    MSG = 'Line is too long. [%d/%d]'
+
+    on_start do |_sexp|
+      max_length = config['max']
+      dummy_node = Struct.new(:line)
+
+      document.source_lines.each_with_index do |line, index|
+        next if line.length <= max_length
+
+        report_lint(dummy_node.new(index + 1), format(MSG, line.length, max_length))
+      end
+    end
+  end
+end

data/lib/slim_lint/linter/redundant_div.rb

@@ -0,0 +1,17 @@
+module SlimLint
+  # Checks for unnecessary uses of the `div` tag where a class name or ID
+  # already implies a div.
+  class Linter::RedundantDiv < Linter
+    include LinterRegistry
+
+    MESSAGE = '`div` is redundant when %s attribute shortcut is present'
+
+    on [:html, :tag, 'div', [:html, :attrs, [:html, :attr, 'class', [:static]]]] do |sexp|
+      report_lint(sexp, MESSAGE % 'class')
+    end
+
+    on [:html, :tag, 'div', [:html, :attrs, [:html, :attr, 'id', [:static]]]] do |sexp|
+      report_lint(sexp, MESSAGE % 'id')
+    end
+  end
+end