slim_lint 0.2.0 → 0.3.0

data/lib/slim_lint/linter/rubocop.rb

@@ -14,12 +14,18 @@ module SlimLint
       extractor = SlimLint::RubyExtractor.new
       extracted_ruby = extractor.extract(processed_sexp)
 
-      find_lints(extractor, extracted_ruby) unless extracted_ruby.empty?
+      find_lints(extracted_ruby, extractor.source_map) unless extracted_ruby.empty?
     end
 
     private
 
-    def find_lints(extractor, ruby)
+    # Executes RuboCop against the given Ruby code and records the offenses as
+    # lints.
+    #
+    # @param ruby [String] Ruby code
+    # @param source_map [Hash] map of Ruby code line numbers to original line
+    #   numbers in the template
+    def find_lints(ruby, source_map)
       rubocop = ::RuboCop::CLI.new
 
       original_filename = document.file || 'ruby_script'
@@ -30,7 +36,7 @@ module SlimLint
         begin
           f.write(ruby)
           f.close
-          extract_lints_from_offences(lint_file(rubocop, f.path), extractor)
+          extract_lints_from_offenses(lint_file(rubocop, f.path), source_map)
         ensure
           f.unlink
         end
@@ -38,36 +44,52 @@ module SlimLint
     end
 
     # Defined so we can stub the results in tests
+    #
+    # @param rubocop [RuboCop::CLI]
+    # @param file [String]
+    # @return [Array<RuboCop::Cop::Offense>]
     def lint_file(rubocop, file)
-      rubocop.run(%w[--format SlimLint::OffenceCollector] << file)
-      OffenceCollector.offences
+      rubocop.run(%w[--format SlimLint::OffenseCollector] << file)
+      OffenseCollector.offenses
     end
 
-    def extract_lints_from_offences(offences, extractor)
-      offences.select { |offence| !config['ignored_cops'].include?(offence.cop_name) }
-              .each do |offence|
+    # Aggregates RuboCop offenses and converts them to {SlimLint::Lint}s
+    # suitable for reporting.
+    #
+    # @param offenses [Array<RuboCop::Cop::Offense>]
+    # @param source_map [Hash]
+    def extract_lints_from_offenses(offenses, source_map)
+      offenses.select { |offense| !config['ignored_cops'].include?(offense.cop_name) }
+              .each do |offense|
         @lints << Lint.new(self,
                            document.file,
-                           extractor.source_map[offence.line],
-                           "#{offence.cop_name}: #{offence.message}")
+                           source_map[offense.line],
+                           "#{offense.cop_name}: #{offense.message}")
       end
     end
   end
 
-  # Collects offences detected by RuboCop.
-  class OffenceCollector < ::RuboCop::Formatter::BaseFormatter
-    attr_accessor :offences
-
+  # Collects offenses detected by RuboCop.
+  class OffenseCollector < ::RuboCop::Formatter::BaseFormatter
     class << self
-      attr_accessor :offences
+      # List of offenses reported by RuboCop.
+      attr_accessor :offenses
     end
 
+    # Executed when RuboCop begins linting.
+    #
+    # @param _target_files [Array<String>]
     def started(_target_files)
-      self.class.offences = []
+      self.class.offenses = []
     end
 
-    def file_finished(_file, offences)
-      self.class.offences += offences
+    # Executed when a file has been scanned by RuboCop, adding the reported
+    # offenses to our collection.
+    #
+    # @param _file [String]
+    # @param offenses [Array<RuboCop::Cop::Offense>]
+    def file_finished(_file, offenses)
+      self.class.offenses += offenses
     end
   end
 end

data/lib/slim_lint/linter/tag_case.rb

@@ -5,7 +5,7 @@ module SlimLint
 
     on [:html, :tag] do |sexp|
       _, _, name = sexp
-      next unless name =~ /[A-Z]/
+      next unless name[/[A-Z]/]
 
       report_lint(sexp, "Tag `#{name}` should be written as `#{name.downcase}`")
     end

data/lib/slim_lint/linter.rb

@@ -1,22 +1,29 @@
 module SlimLint
   # Base implementation for all lint checks.
+  #
+  # @abstract
   class Linter
     # Include definitions for Sexp pattern-matching helpers.
     include SexpVisitor
     extend SexpVisitor::DSL
 
-    # TODO: Remove once spec support returns an array of lints instead of a
-    # linter
+    # List of lints reported by this linter.
+    #
+    # @todo Remove once spec/support/shared_linter_context returns an array of
+    #   lints for the subject instead of the linter itself.
     attr_reader :lints
 
+    # Initializes a linter with the specified configuration.
+    #
     # @param config [Hash] configuration for this linter
     def initialize(config)
       @config = config
       @lints = []
-      @ruby_parser = nil
     end
 
-    # Runs the linter against the specified Sexp
+    # Runs the linter against the given Slim document.
+    #
+    # @param document [SlimLint::Document]
     def run(document)
       @document = document
       @lints = []
@@ -25,6 +32,8 @@ module SlimLint
     end
 
     # Returns the simple name for this linter.
+    #
+    # @return [String]
     def name
       self.class.name.split('::').last
     end
@@ -34,12 +43,16 @@ module SlimLint
     attr_reader :config, :document
 
     # Record a lint for reporting back to the user.
-    def report_lint(sexp, message)
-      @lints << SlimLint::Lint.new(self, @document.file, sexp.line, message)
+    #
+    # @param node [#line] node to extract the line number from
+    # @param message [String] error/warning to display to the user
+    def report_lint(node, message)
+      @lints << SlimLint::Lint.new(self, @document.file, node.line, message)
     end
 
     # Parse Ruby code into an abstract syntax tree.
     #
+    # @param source [String] Ruby code to parse
     # @return [AST::Node]
     def parse_ruby(source)
       @ruby_parser ||= SlimLint::RubyParser.new

data/lib/slim_lint/linter_registry.rb

@@ -6,12 +6,23 @@ module SlimLint
     @linters = []
 
     class << self
+      # List of all registered linters.
       attr_reader :linters
 
-      def included(base)
-        @linters << base
+      # Executed when a linter includes the {LinterRegistry} module.
+      #
+      # This results in the linter being registered with the registry.
+      #
+      # @param subclass [Class]
+      def included(subclass)
+        @linters << subclass
       end
 
+      # Return a list of {SlimLint::Linter} {Class}es corresponding to the
+      # specified list of names.
+      #
+      # @param linter_names [Array<String>]
+      # @return [Array<Class>]
       def extract_linters_from(linter_names)
         linter_names.map do |linter_name|
           begin

data/lib/slim_lint/linter_selector.rb

@@ -0,0 +1,74 @@
+module SlimLint
+  # Chooses the appropriate linters to run given the specified configuration.
+  class LinterSelector
+    # Creates a selector using the given configuration and additional options.
+    def initialize(config, options)
+      @config = config
+      @options = options
+    end
+
+    # Returns the set of linters to run against the given file.
+    #
+    # @param file [String]
+    # @raise [SlimLint::Exceptions::NoLintersError] when no linters are enabled
+    # @return [Array<SlimLint::Linter>]
+    def linters_for_file(file)
+      @linters ||= extract_enabled_linters(@config, @options)
+      @linters.select { |linter| run_linter_on_file?(@config, linter, file) }
+    end
+
+    private
+
+    # Returns a list of linters that are enabled given the specified
+    # configuration and additional options.
+    #
+    # @param config [SlimLint::Configuration]
+    # @param options [Hash]
+    # @return [Array<SlimLint::Linter>]
+    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
+      linters = (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
+
+      # Highlight condition where all linters were filtered out, as this was
+      # likely a mistake on the user's part
+      if linters.empty?
+        raise SlimLint::Exceptions::NoLintersError, 'No linters specified'
+      end
+
+      linters
+    end
+
+    # Whether to run the given linter against the specified file.
+    #
+    # @param config [SlimLint::Configuration]
+    # @param linter [SlimLint::Linter]
+    # @param file [String]
+    # @return [Boolean]
+    def run_linter_on_file?(config, linter, file)
+      linter_config = config.for_linter(linter)
+
+      if linter_config['include'].any? &&
+         !SlimLint::Utils.any_glob_matches?(linter_config['include'], file)
+        return false
+      end
+
+      if SlimLint::Utils.any_glob_matches?(linter_config['exclude'], file)
+        return false
+      end
+
+      true
+    end
+  end
+end

data/lib/slim_lint/logger.rb

@@ -73,15 +73,6 @@ module SlimLint
       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}.
     #
@@ -100,6 +91,11 @@ module SlimLint
 
     private
 
+    # Print output in the specified color.
+    #
+    # @param code [Integer,String] ANSI color code
+    # @param output [String] output to print
+    # @param newline [Boolean] whether to append a newline
     def color(code, output, newline = true)
       log(color_enabled ? "\033[#{code}m#{output}\033[0m" : output, newline)
     end

data/lib/slim_lint/matcher/anything.rb

@@ -0,0 +1,9 @@
+module SlimLint::Matcher
+  # Will match anything, acting as a wildcard.
+  class Anything < Base
+    # @see {SlimLint::Matcher::Base#match?}
+    def match?(*)
+      true
+    end
+  end
+end

data/lib/slim_lint/matcher/base.rb

@@ -0,0 +1,19 @@
+module SlimLint::Matcher
+  # Represents a Sexp pattern implementing complex matching logic.
+  #
+  # Subclasses can implement custom logic to create complex matches that can be
+  # reused across linters, DRYing up matching code.
+  #
+  # @abstract
+  class Base
+    # Whether this matcher matches the specified object.
+    #
+    # This must be implemented by subclasses.
+    #
+    # @param other [Object]
+    # @return [Boolean]
+    def match?(*)
+      raise NotImplementedError, 'Matcher must implement `match?`'
+    end
+  end
+end

data/lib/slim_lint/matcher/capture.rb

@@ -0,0 +1,30 @@
+module SlimLint::Matcher
+  # Wraps a matcher, taking on the behavior of the wrapped matcher but storing
+  # the value that matched so it can be referred to later.
+  class Capture < Base
+    # @return [SlimLint::Matcher::Base] matcher that this capture wraps
+    attr_accessor :matcher
+
+    # @return [Object] value that was captured
+    attr_accessor :value
+
+    # Creates a capture that wraps that given matcher.
+    #
+    # @param matcher [SlimLint::Matcher::Base]
+    # @return [SlimLint::Matcher::Capture]
+    def self.from_matcher(matcher)
+      new.tap do |cap_matcher|
+        cap_matcher.matcher = matcher
+      end
+    end
+
+    # @see {SlimLint::Matcher::Base#match?}
+    def match?(object)
+      if result = @matcher.match?(object)
+        @value = object
+      end
+
+      result
+    end
+  end
+end

data/lib/slim_lint/matcher/nothing.rb

@@ -0,0 +1,11 @@
+module SlimLint::Matcher
+  # Does not match anything.
+  #
+  # This is used in specs.
+  class Nothing < Base
+    # @see {SlimLint::Matcher::Base#match?}
+    def match?(*)
+      false
+    end
+  end
+end

data/lib/slim_lint/options.rb

@@ -30,12 +30,8 @@ module SlimLint
 
     private
 
+    # Register linter-related flags.
     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
@@ -48,10 +44,23 @@ module SlimLint
 
       parser.on('-r', '--reporter reporter', String,
                 'Specify which reporter you want to use to generate the output') do |reporter|
-        @options[:reporter] = SlimLint::Reporter.const_get("#{reporter.capitalize}Reporter")
+        @options[:reporter] = load_reporter_class(reporter.capitalize)
       end
     end
 
+    # Returns the class of the specified Reporter.
+    #
+    # @param reporter_name [String]
+    # @raise [SlimLint::Exceptions::InvalidCLIOption] if reporter doesn't exist
+    # @return [Class]
+    def load_reporter_class(reporter_name)
+      SlimLint::Reporter.const_get("#{reporter_name}Reporter")
+    rescue NameError
+      raise SlimLint::Exceptions::InvalidCLIOption,
+            "#{reporter_name}Reporter does not exist"
+    end
+
+    # Register file-related flags.
     def add_file_options(parser)
       parser.on('-c', '--config config-file', String,
                 'Specify which configuration file you want to use') do |conf_file|
@@ -64,6 +73,7 @@ module SlimLint
       end
     end
 
+    # Register informational flags.
     def add_info_options(parser)
       parser.on('--show-linters', 'Display available linters') do
         @options[:show_linters] = true

data/lib/slim_lint/rake_task.rb

@@ -51,6 +51,8 @@ module SlimLint
     attr_accessor :quiet
 
     # Create the task so it exists in the current namespace.
+    #
+    # @param name [Symbol] task name
     def initialize(name = :slim_lint)
       @name = name
       @files = ['.'] # Search for everything under current directory by default
@@ -63,6 +65,7 @@ module SlimLint
 
     private
 
+    # Defines the Rake task.
     def define
       desc default_description unless ::Rake.application.last_description
 
@@ -75,6 +78,9 @@ module SlimLint
       end
     end
 
+    # Executes the CLI given the specified task arguments.
+    #
+    # @param task_args [Rake::TaskArguments]
     def run_cli(task_args)
       cli_args = ['--config', config] if config
 
@@ -84,6 +90,10 @@ module SlimLint
       fail "#{SlimLint::APP_NAME} failed with exit code #{result}" unless result == 0
     end
 
+    # Returns the list of files that should be linted given the specified task
+    # arguments.
+    #
+    # @param task_args [Rake::TaskArguments]
     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
@@ -96,6 +106,11 @@ module SlimLint
     end
 
     # Friendly description that shows the full command that will be executed.
+    #
+    # This allows us to change the information displayed by `rake --tasks` based
+    # on the options passed to the constructor which defined the task.
+    #
+    # @return [String]
     def default_description
       description = "Run `#{SlimLint::APP_NAME}"
       description += " --config #{config}" if config

data/lib/slim_lint/report.rb

@@ -1,9 +1,16 @@
 module SlimLint
   # Contains information about all lints detected during a scan.
   class Report
+    # List of lints that were found.
     attr_accessor :lints
+
+    # List of files that were linted.
     attr_reader :files
 
+    # Creates a report.
+    #
+    # @param lints [Array<SlimLint::Lint>] lints that were found
+    # @param files [Array<String>] files that were linted
     def initialize(lints, files)
       @lints = lints.sort_by { |l| [l.filename, l.line] }
       @files = files

data/lib/slim_lint/reporter/default_reporter.rb

@@ -2,8 +2,8 @@ module SlimLint
   # 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] }
+    def display_report(report)
+      sorted_lints = report.lints.sort_by { |l| [l.filename, l.line] }
 
       sorted_lints.each do |lint|
         print_location(lint)

data/lib/slim_lint/reporter/json_reporter.rb

@@ -1,29 +1,34 @@
 module SlimLint
   # Outputs report as a JSON document.
   class Reporter::JsonReporter < Reporter
-    def report_lints
+    def display_report(report)
+      lints = report.lints
       grouped = lints.group_by(&:filename)
 
-      report = {
-        metadata: {
-          slim_lint_version: SlimLint::VERSION,
-          ruby_engine:      RUBY_ENGINE,
-          ruby_patchlevel:  RUBY_PATCHLEVEL.to_s,
-          ruby_platform:    RUBY_PLATFORM,
-        },
+      report_hash = {
+        metadata: metadata,
         files: grouped.map { |l| map_file(l) },
         summary: {
           offense_count: lints.length,
           target_file_count: grouped.length,
-          inspected_file_count: files.length,
+          inspected_file_count: report.files.length,
         },
       }
 
-      log.log report.to_json
+      log.log report_hash.to_json
     end
 
     private
 
+    def metadata
+      {
+        slim_lint_version: SlimLint::VERSION,
+        ruby_engine:      RUBY_ENGINE,
+        ruby_patchlevel:  RUBY_PATCHLEVEL.to_s,
+        ruby_platform:    RUBY_PLATFORM,
+      }
+    end
+
     def map_file(file)
       {
         path: file.first,

data/lib/slim_lint/reporter.rb

@@ -1,36 +1,42 @@
 module SlimLint
-  # Abstract lint reporter. Subclass and override {#report_lints} to
+  # Abstract lint reporter. Subclass and override {#display_report} to
   # implement a custom lint reporter.
   #
   # @abstract
   class Reporter
-    attr_reader :lints
-    attr_reader :files
-
+    # Creates the reporter that will display the given report.
+    #
     # @param logger [SlimLint::Logger]
-    # @param report [SlimLint::Report]
-    def initialize(logger, report)
+    def initialize(logger)
       @log = logger
-      @lints = report.lints
-      @files = report.files
     end
 
     # Implemented by subclasses to display lints from a {SlimLint::Report}.
-    def report_lints
-      raise NotImplementedError
+    #
+    # @param report [SlimLint::Report]
+    def display_report(report)
+      raise NotImplementedError,
+            "Implement `display_report` to display #{report}"
     end
 
-    # Keep tracking all the descendants of this class for the list of available reporters
+    # Keep tracking all the descendants of this class for the list of available
+    # reporters.
+    #
+    # @return [Array<Class>]
     def self.descendants
       @descendants ||= []
     end
 
+    # Executed when this class is subclassed.
+    #
+    # @param descendant [Class]
     def self.inherited(descendant)
       descendants << descendant
     end
 
     private
 
+    # @return [SlimLint::Logger] logger to send output to
     attr_reader :log
   end
 end

data/lib/slim_lint/ruby_extractor.rb

@@ -30,6 +30,8 @@ module SlimLint
     include SexpVisitor
     extend SexpVisitor::DSL
 
+    # Map of generated Ruby source code lines and their corresponding lines in
+    # the original document.
     attr_reader :source_map
 
     # Extracts Ruby code from Sexp representing a Slim document.