slim_lint 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 90417095e752ffc02b70c6cf2c7c578642a7aced
-  data.tar.gz: db37d397d726e455c2d98e565c1f0a4ba876c28f
+  metadata.gz: 66e3790d144eb2141cb93b53835a447cfe9e1db8
+  data.tar.gz: 7b07131e272e1b913926061eb37703d7e0738f01
 SHA512:
-  metadata.gz: d08877671cd10ae219e055f65f16c9dc26800b4aac6fe0be74dcd669da2da0bcdf45ec7885b24c87333c7731fe1178a7c0c45259146ff7c285da6371b7da53da
-  data.tar.gz: 1afec4e606480b536283d722121dc662fc0d6b2da4cd5bfeb3c93e4853b113404459a6e012546cd0fb179f99888983fa7ce0880f5f02bfcb5944acb163817c19
+  metadata.gz: d776fde028a429d5a44ae2cdc4092705e759a96f82dca6c2b59ad6a3fc1280823e86ecee38fa642f3720d048567ab31a3dd1bd5bf72a48ef3737c2b1d300843f
+  data.tar.gz: e617bc89440a83feefec3beabaa186ef57fb8c5433fd7b134610deaf631a4b4ad3c0e1e70474255145d2b40fc5d19ee3f19191ab102329b4f5a5dc27d9995717

data/bin/slim-lint

@@ -1,6 +1,5 @@
 #!/usr/bin/env ruby
 
-require 'slim_lint'
 require 'slim_lint/cli'
 
 logger = SlimLint::Logger.new(STDOUT)

data/lib/slim_lint/atom.rb

@@ -0,0 +1,91 @@
+module SlimLint
+  # Represents an atomic, childless, literal value within an S-expression.
+  #
+  # This creates a light wrapper around literal values of S-expressions so we
+  # can make an {Atom} quack like a {Sexp} without being an {Sexp}.
+  class Atom
+    # Creates an atom from the specified value.
+    #
+    # @param value [Object]
+    def initialize(value)
+      @value = value
+    end
+
+    # Returns whether this atom is equivalent to another object.
+    #
+    # This defines a helper which unwraps the inner value of the atom to compare
+    # against a literal value, saving us having to do it ourselves everywhere
+    # else.
+    #
+    # @param other [Object]
+    # @return [Boolean]
+    def ==(other)
+      case other
+      when Atom
+        @value == other.instance_variable_get(:@value)
+      else
+        @value == other
+      end
+    end
+
+    # Returns whether this atom matches the given Sexp pattern.
+    #
+    # This exists solely to make an {Atom} quack like a {Sexp}, so we don't have
+    # to manually check the type when doing comparisons elsewhere.
+    #
+    # @param [Array, Object]
+    # @return [Boolean]
+    def match?(pattern)
+      # Delegate matching logic if we're comparing against a matcher
+      if pattern.is_a?(SlimLint::Matcher::Base)
+        return pattern.match?(@value)
+      end
+
+      @value == pattern
+    end
+
+    # Displays the string representation the value this {Atom} wraps.
+    #
+    # @return [String]
+    def to_s
+      @value.to_s
+    end
+
+    # Displays a string representation of this {Atom} suitable for debugging.
+    #
+    # @return [String]
+    def inspect
+      "<#Atom #{@value.inspect}>"
+    end
+
+    # Redirect methods to the value this {Atom} wraps.
+    #
+    # Again, this is for convenience so we don't need to manually unwrap the
+    # value ourselves. It's pretty magical, but results in much DRYer code.
+    #
+    # @param method_sym [Symbol] method that was called
+    # @param args [Array]
+    # @yield block that was passed to the method
+    def method_missing(method_sym, *args, &block)
+      if @value.respond_to?(method_sym)
+        @value.send(method_sym, *args, &block)
+      else
+        super
+      end
+    end
+
+    # Return whether this {Atom} or the value it wraps responds to the given
+    # message.
+    #
+    # @param method_sym [Symbol]
+    # @param include_private [Boolean]
+    # @return [Boolean]
+    def respond_to?(method_sym, include_private = false)
+      if super
+        true
+      else
+        @value.respond_to?(method_sym, include_private)
+      end
+    end
+  end
+end

data/lib/slim_lint/capture_map.rb

@@ -0,0 +1,17 @@
+module SlimLint
+  # Holds the list of captures, providing a convenient interface for accessing
+  # the values and unwrapping them on your behalf.
+  class CaptureMap < Hash
+    # Returns the captured value with the specified name.
+    #
+    # @param capture_name [Symbol]
+    # @return [Object]
+    def [](capture_name)
+      if key?(capture_name)
+        super.value
+      else
+        raise ArgumentError, "Capture #{capture_name.inspect} does not exist!"
+      end
+    end
+  end
+end

data/lib/slim_lint/cli.rb

@@ -1,3 +1,4 @@
+require 'slim_lint'
 require 'slim_lint/options'
 
 require 'sysexits'
@@ -5,8 +6,8 @@ require 'sysexits'
 module SlimLint
   # Command line application interface.
   class CLI
-    attr_accessor :options
-
+    # Create a CLI that outputs to the specified logger.
+    #
     # @param logger [SlimLint::Logger]
     def initialize(logger)
       @log = logger
@@ -16,7 +17,7 @@ module SlimLint
     # 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 = SlimLint::Options.new.parse(args)
       act_on_options(options)
@@ -28,6 +29,9 @@ module SlimLint
 
     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 SlimLint
       end
     end
 
+    # Outputs a message and returns an appropriate error code for the specified
+    # exception.
     def handle_exception(ex)
       case ex
       when SlimLint::Exceptions::ConfigurationError
@@ -69,21 +75,27 @@ module SlimLint
       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,
+                               SlimLint::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 = SlimLint::LinterRegistry.linters.map do |linter|
         linter.name.split('::').last
       end
 
@@ -92,10 +104,11 @@ module SlimLint
       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 = SlimLint::Reporter.descendants.map do |reporter|
         reporter.name.split('::').last.sub(/Reporter$/, '').downcase
       end
 
@@ -104,14 +117,18 @@ module SlimLint
       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} #{SlimLint::VERSION}"
+      log.log "#{SlimLint::APP_NAME} #{SlimLint::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/slim_lint/configuration.rb

@@ -1,6 +1,12 @@
 module SlimLint
   # 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,8 @@ module SlimLint
       validate
     end
 
+    # Access the configuration as if it were a hash.
+    #
     # @param key [String]
     # @return [Array,Hash,Number,String]
     def [](key)
@@ -36,19 +44,9 @@ module SlimLint
           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
+      @hash['linters'].fetch(linter_name, {}).dup.freeze
     end
 
     # Merges the given configuration with this one, returning a new
@@ -62,13 +60,11 @@ module SlimLint
 
     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
@@ -80,21 +76,32 @@ module SlimLint
       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
     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
+    # 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
   end

data/lib/slim_lint/configuration_loader.rb

@@ -8,6 +8,8 @@ module SlimLint
     CONFIG_FILE_NAME = '.slim-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 SlimLint
         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 [SlimLint::Configuration]
       def load_file(file)
         config = load_from_file(file)
 
         default_configuration.merge(config)
-      rescue => error
+      rescue Psych::SyntaxError, Errno::ENOENT => error
         raise SlimLint::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 [SlimLint::Configuration]
       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
 
+      # Parses and loads a configuration from the given file.
+      #
+      # @param file [String]
+      # @return [SlimLint::Configuration]
       def load_from_file(file)
         hash =
           if yaml = YAML.load_file(file)
@@ -57,6 +68,11 @@ module SlimLint
         SlimLint::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/slim_lint/document.rb

@@ -1,7 +1,23 @@
 module SlimLint
   # Represents a parsed Slim document and its associated metadata.
   class Document
-    attr_reader :config, :file, :sexp, :source, :source_lines
+    # File name given to source code parsed from just a string.
+    STRING_SOURCE = '(string)'
+
+    # @return [SlimLint::Configuration] Configuration used to parse template
+    attr_reader :config
+
+    # @return [String] Slim template file path
+    attr_reader :file
+
+    # @return [SlimLint::Sexp] Sexpression representing the parsed document
+    attr_reader :sexp
+
+    # @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 Slim code into a {Document}.
     #
@@ -11,7 +27,7 @@ module SlimLint
     # @raise [Slim::Parser::Error] if there was a problem parsing the document
     def initialize(source, options)
       @config = options[:config]
-      @file = options.fetch(:file, '(string)')
+      @file = options.fetch(:file, STRING_SOURCE)
 
       process_source(source)
     end
@@ -24,8 +40,8 @@ module SlimLint
       @source = strip_frontmatter(source)
       @source_lines = @source.split("\n")
 
-      @engine = SlimLint::Engine.new(file: @file)
-      @sexp = @engine.call(source)
+      engine = SlimLint::Engine.new(file: @file)
+      @sexp = engine.parse(source)
     end
 
     # Removes YAML frontmatter

data/lib/slim_lint/engine.rb

@@ -23,5 +23,11 @@ module SlimLint
 
     # Annotates Sexps with line numbers
     use SlimLint::Filters::InjectLineNumbers
+
+    # Parses the given source code into a Sexp.
+    #
+    # @param source [String] source code to parse
+    # @return [SlimLint::Sexp] parsed Sexp
+    alias_method :parse, :call
   end
 end

data/lib/slim_lint/file_finder.rb

@@ -8,6 +8,8 @@ module SlimLint
     # is specified instead of a file.
     VALID_EXTENSIONS = %w[.slim]
 
+    # Create a file finder using the specified configuration.
+    #
     # @param config [SlimLint::Configuration]
     def initialize(config)
       @config = config
@@ -22,15 +24,18 @@ module SlimLint
     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
+          SlimLint::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 SlimLint
         end
       end
 
-      files.uniq
+      files.uniq.sort
     end
 
+    # Whether the given file should be treated as a Slim file.
+    #
+    # @param file [String]
+    # @return [Boolean]
     def slim_file?(file)
       return false unless ::FileTest.file?(file)
 

data/lib/slim_lint/filters/inject_line_numbers.rb

@@ -5,8 +5,13 @@ module SlimLint::Filters
   # 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]
+    # {Sexp} representing a newline.
+    NEWLINE_SEXP = SlimLint::Sexp.new([:newline])
 
+    # Annotates the given {SlimLint::Sexp} with line number information.
+    #
+    # @param sexp [SlimLint::Sexp]
+    # @return [SlimLint::Sexp]
     def call(sexp)
       @line_number = 1
       traverse(sexp)
@@ -16,7 +21,7 @@ module SlimLint::Filters
     private
 
     # Traverses an {Sexp}, annotating it with line numbers by searching for
-    # :newline abstractions within it.
+    # newline abstractions within it.
     #
     # @param sexp [SlimLint::Sexp]
     def traverse(sexp)

data/lib/slim_lint/filters/sexp_converter.rb

@@ -4,6 +4,10 @@ module SlimLint::Filters
   # These {SlimLint::Sexp}s include additional helpers that makes working with
   # them more pleasant.
   class SexpConverter < Temple::Filter
+    # Converts the given {Array} to a {SlimLint::Sexp}.
+    #
+    # @param array_sexp [Array]
+    # @return [SlimLint::Sexp]
     def call(array_sexp)
       SlimLint::Sexp.new(array_sexp)
     end

data/lib/slim_lint/lint.rb

@@ -1,7 +1,20 @@
 module SlimLint
   # Contains information about a problem or issue with a Slim 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 SlimLint
       @severity = severity
     end
 
+    # Return whether this lint has a severity of error.
+    #
+    # @return [Boolean]
     def error?
       @severity == :error
     end

data/lib/slim_lint/linter/comment_control_statement.rb

@@ -5,13 +5,13 @@ module SlimLint
 
     on [:slim, :control] do |sexp|
       _, _, code = sexp
-      next unless code =~ /\A\s*#/
+      next unless code[/\A\s*#/]
 
       comment = code[/\A\s*#(.*\z)/, 1]
 
       report_lint(sexp,
                   "Slim code comments (`/#{comment}`) are preferred over " \
-                  "control statement comments (`-# #{comment}`)")
+                  "control statement comments (`-##{comment}`)")
     end
   end
 end

data/lib/slim_lint/linter/consecutive_control_statements.rb

@@ -6,27 +6,12 @@ module SlimLint
 
     on [:multi] do |sexp|
       Utils.for_consecutive_items(sexp,
-                                  method(:code_sexp?),
+                                  ->(nested_sexp) { nested_sexp.match?([:slim, :control]) },
                                   config['max_consecutive'] + 1) do |group|
         report_lint(group.first,
                     "#{group.count} consecutive control statements can be " \
                     'merged into a single `ruby:` filter')
       end
     end
-
-    private
-
-    # Returns whether the given Sexp is a :code abstraction.
-    #
-    # @param sexp [SlimLint::Sexp]
-    # @return [Boolean]
-    def code_sexp?(sexp)
-      # TODO: Switch this with a built-in method on the {Sexp} object itself
-      sexp.is_a?(Sexp) && sexp.match?([:slim, :control])
-    end
-
-    def newline_sexp?(sexp)
-      sexp.is_a?(Sexp) && sexp.first == :newline
-    end
   end
 end

data/lib/slim_lint/linter/empty_control_statement.rb

@@ -5,7 +5,7 @@ module SlimLint
 
     on [:slim, :control] do |sexp|
       _, _, code = sexp
-      next unless code =~ /\A\s*\Z/
+      next unless code[/\A\s*\Z/]
 
       report_lint(sexp, 'Empty control statement can be removed')
     end

data/lib/slim_lint/linter/redundant_div.rb

@@ -6,12 +6,15 @@ module SlimLint
 
     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,
+             capture(:attr_name, anything),
+             [:static]]]] do |sexp|
+      attr = captures[:attr_name]
+      next unless %w[class id].include?(attr)
 
-    on [:html, :tag, 'div', [:html, :attrs, [:html, :attr, 'id', [:static]]]] do |sexp|
-      report_lint(sexp, MESSAGE % 'id')
+      report_lint(sexp, MESSAGE % attr)
     end
   end
 end