lint_trappings 0.1.0

data/lib/lint_trappings/formatter_forwarder.rb

@@ -0,0 +1,23 @@
+module LintTrappings
+  # Contains a collection of formatters and their output destinations, exposing
+  # them a single formatter.
+  #
+  # This quacks like a Formatter so that it can be used in place of a single
+  # formatter, but fans out the calls to all formatters in the collection.
+  class FormatterForwarder
+    def initialize(formatters)
+      @formatters = formatters
+    end
+
+    %i[
+      started
+      job_started
+      job_finished
+      finished
+    ].each do |method_sym|
+      define_method method_sym do |*args|
+        @formatters.each { |formatter| formatter.send(method_sym, *args) }
+      end
+    end
+  end
+end

data/lib/lint_trappings/formatter_loader.rb

@@ -0,0 +1,45 @@
+module LintTrappings
+  # Loads the configured formatters.
+  class FormatterLoader
+    def initialize(application, config, output)
+      @application = application
+      @config = config
+      @output = output
+    end
+
+    def load(options)
+      outputs = options.fetch(:formatters, [{ 'Default' => :stdout }])
+
+      outputs.map do |output_specification|
+        output_specification.map do |formatter_name, output_path|
+          load_formatter(formatter_name)
+          create_formatter(formatter_name, output_path, options)
+        end
+      end.flatten
+    end
+
+    private
+
+    def load_formatter(formatter_name)
+      formatter_path = File.join('lint_trappings', 'formatter', Utils.snake_case(formatter_name))
+      require formatter_path
+    rescue LoadError, SyntaxError => ex
+      raise FormatterLoadError,
+            "Unable to load formatter `#{formatter_name}`: #{ex.message}"
+    end
+
+    def create_formatter(formatter_name, output_path, options)
+      output_dest =
+        if output_path == :stdout
+          @output
+        else
+          Output.new(File.open(output_path, File::CREAT | File::WRONLY))
+        end
+
+      Formatter.const_get(formatter_name).new(@application, @config, options, output_dest)
+    rescue NameError => ex
+      raise FormatterLoadError,
+            "Unable to create formatter `#{formatter_name}`: #{ex.message}"
+    end
+  end
+end

data/lib/lint_trappings/lint.rb

@@ -0,0 +1,37 @@
+module LintTrappings
+  # Contains information about a problem or issue with a document.
+  class Lint
+    # @return [LintTrappings::Linter, nil] linter that reported the lint (if applicable)
+    attr_reader :linter
+
+    # @return [String] file path to which the lint applies
+    attr_reader :path
+
+    # @return [Range<LintTrappings::Location>] source range of the problem within the file
+    attr_reader :source_range
+
+    # @return [String] message describing the lint
+    attr_reader :message
+
+    # @return [Symbol] whether this lint is a warning or an error
+    attr_reader :severity
+
+    # @return [Exception] the exception that was raised, if any
+    attr_reader :exception
+
+    # @param options [Hash]
+    # @option options :linter [LintTrappings::Linter] optional
+    # @option options :path [String]
+    # @option options :source_range [Range<LintTrappings::Location>]
+    # @option options :message [String]
+    # @option options :severity [Symbol]
+    def initialize(options)
+      @linter       = options[:linter]
+      @path         = options.fetch(:path)
+      @source_range = options.fetch(:source_range)
+      @message      = options.fetch(:message)
+      @severity     = options.fetch(:severity)
+      @exception    = options[:exception]
+    end
+  end
+end

data/lib/lint_trappings/linter.rb

@@ -0,0 +1,182 @@
+require 'lint_trappings/linter_configuration_validator'
+require 'ostruct'
+
+module LintTrappings
+  # Base implementation for all lint checks.
+  #
+  # @abstract
+  class Linter
+    class << self
+      # Return all subclasses.
+      #
+      # @return [Array<Class>]
+      def descendants
+        ObjectSpace.each_object(Class).select { |klass| klass < self }
+      end
+
+      # Returns the canonical name for this linter class.
+      #
+      # The canonical name is used as the key for configuring the linter in the
+      # configuration file, or when referring to it from the command line.
+      #
+      # This uses the "Linter" module as an indicator of when to start removing
+      # unnecessary module prefixes.
+      #
+      # @example
+      #   LintTrappings::Linter::MyLinter
+      #   => "MyLinter"
+      #
+      # @example
+      #   MyCustomNamespace::MyLinter
+      #   => "MyCustomNamespace::MyLinter"
+      #
+      # @example
+      #   MyModule::Linter::MyCustomNamespace::MyLinter
+      #   => "MyCustomNamespace::MyLinter"
+      #
+      # @return [String]
+      def canonical_name
+        @canonical_name ||=
+          begin
+            full_name = name.to_s.split('::')
+
+            if linter_class_index = full_name.index('Linter')
+              # Otherwise, the name follows the `Linter` module
+              linter_class_index += 1
+            else
+              # If not found, include the full name
+              linter_class_index = 0
+            end
+
+            full_name[linter_class_index..-1].join('::')
+          end
+      end
+
+      def description(*args)
+        if args.any?
+          @description = args.first
+        else
+          @description
+        end
+      end
+
+      def option(name, options)
+        options = options.dup
+
+        @options_spec ||= {}
+        opt = @options_spec[name] = {}
+        %i[type default description].each do |option_sym|
+          opt[option_sym] = options.delete(option_sym) if options[option_sym]
+        end
+
+        if options.keys.any?
+          raise InvalidOptionSpecificationError,
+                "Unknown key `#{options.keys.first}` for `#{name}` option " \
+                "specification on linter #{self}"
+        end
+      end
+
+      def options
+        @options_spec || {}
+      end
+
+      attr_accessor :options_struct_class
+    end
+
+    # Initializes a linter with the specified configuration.
+    #
+    # @param config [Hash] configuration for this linter
+    def initialize(config)
+      @orig_hash_config = @config = config
+      validate_options_specification
+      @config = convert_config_hash_to_struct(@config)
+      @lints = []
+    end
+
+    # Runs the linter against the given Slim document.
+    #
+    # @param document [LintTrappings::Document]
+    def run(document)
+      @document = document
+      @lints = []
+      scan
+      @lints
+    end
+
+    # Returns the canonical name of this linter's class.
+    #
+    # @see {LintTrappings::Linter.canonical_name}
+    #
+    # @return [String]
+    def canonical_name
+      self.class.canonical_name
+    end
+
+    private
+
+    attr_reader :config, :document, :lints
+
+    # Scans the document for lints.
+    def scan
+      raise NotImplementedError, 'Subclass must implement #scan'
+    end
+
+    def validate_options_specification
+      LinterConfigurationValidator.new.validate(self, @config, self.class.options)
+    end
+
+    # List of built-in hook options which are available to every hook
+    BUILT_IN_HOOK_OPTIONS = %w[enabled severity include exclude]
+
+    # Converts a configuration hash to a struct so configuration values are
+    # accessed via method calls. This is valuable as it provides faster feedback
+    # in the event of a typo (you get an error instead of a `nil` value).
+    #
+    # @return [Struct]
+    def convert_config_hash_to_struct(hash)
+      option_names = self.class.options.keys
+      return OpenStruct.new unless option_names.any?
+      self.class.options_struct_class ||= Struct.new(*option_names)
+
+      unknown_keys = (hash.keys - option_names.map(&:to_s) - BUILT_IN_HOOK_OPTIONS)
+      if unknown_keys.any?
+        option_plural = Utils.pluralize('option', unknown_keys.count)
+        raise LinterConfigurationError,
+              "Unknown configuration #{option_plural} for #{canonical_name}: " \
+              "#{unknown_keys.join(', ')}\n" \
+              "Available options: #{(BUILT_IN_HOOK_OPTIONS + option_names).join(', ')}"
+      end
+
+      values = option_names.map { |option_name| hash[option_name.to_s] }
+      self.class.options_struct_class.new(*values)
+    end
+
+    # Record a lint for reporting back to the user.
+    #
+    # @param range [Range<LintTrappings::Location>,#source_range] source range of lint
+    # @param message [String] error/warning to display to the user
+    def report_lint(range_or_obj, message)
+      unless range_or_obj.is_a?(Range) || range_or_obj.respond_to?(:source_range)
+        raise LinterError,
+              '`report_lint` must be given a Range or an object ' \
+              "that responds to `source_range`, but was given: #{range_or_obj.inspect}"
+      end
+
+      @lints << Lint.new(
+        linter: self,
+        path: @document.path,
+        source_range: range_or_obj.is_a?(Range) ? range_or_obj : range_or_obj.source_range,
+        message: message,
+        severity: @orig_hash_config.fetch('severity'),
+      )
+    end
+
+    # Shortcut for creating a range for a single location.
+    #
+    # @return [Range<LintTrappings::Location>]
+    def location(*args)
+      loc = Location.new(*args)
+      loc..loc
+    end
+  end
+end

data/lib/lint_trappings/linter_configuration_validator.rb

@@ -0,0 +1,42 @@
+module LintTrappings
+  # Validates a linter's configuration options.
+  class LinterConfigurationValidator
+    # Verifies the configuration passed to this linter satisfies the options
+    # specifications declared in the linter class.
+    #
+    # @param linter [LintTrappings::Linter]
+    # @param config [Hash]
+    # @param options_specs [Hash]
+    def validate(linter, config, options_specs)
+      insert_default_values(config, options_specs)
+      check_option_types(linter, config, options_specs)
+    end
+
+    private
+
+    def check_option_types(linter, config, options_specs)
+      options_specs.select do |option_name, option_spec|
+        expected_class = option_spec[:type]
+        actual_value = config[option_name.to_s]
+        actual_class = actual_value.class
+
+        # If the class isn't the same or a subclass, it's different
+        next if actual_class <= expected_class
+
+        raise LinterConfigurationError,
+              "Option `#{option_name}` for linter " \
+              "#{linter.canonical_name} must be of " \
+              "type #{expected_class}, but was #{actual_class} (#{actual_value.inspect})!"
+      end
+    end
+
+    def insert_default_values(config, options_specs)
+      options_specs.select do |option_name, option_spec|
+        option_name_str = option_name.to_s
+        next unless option_spec.key?(:default) && !config.key?(option_name_str)
+
+        config[option_name_str] = option_spec[:default]
+      end
+    end
+  end
+end

data/lib/lint_trappings/linter_loader.rb

@@ -0,0 +1,44 @@
+module LintTrappings
+  # Loads linters so they can be run.
+  class LinterLoader
+    def initialize(application, config)
+      @application = application
+      @config = config
+    end
+
+    # Load linters into memory so they can be instantiated.
+    #
+    # @param options [Hash]
+    #
+    # @raise [LinterLoadError] problem loading a linter file/library
+    def load(options)
+      load_directory(@application.linters_directory)
+
+      directories = Array(@config['linter_directories']) + Array(options[:linter_directories])
+      directories.each do |directory|
+        load_directory(directory)
+      end
+    end
+
+    private
+
+    # Recursively load all files in a directory and its subdirectories.
+    def load_directory(directory)
+      # NOTE: While it might seem inefficient to load ALL linters (rather than
+      # only ones which are enabled), the reality is that the difference is
+      # negligible with respect to the application's startup time. It's also
+      # very difficult to do, as you can't infer the file name from the linter
+      # name (since the user can use any naming scheme they desire)
+      Dir[File.join(directory, '**', '*.rb')].each do |path|
+        load_path(path)
+      end
+    end
+
+    def load_path(path)
+      require path
+    rescue LoadError, SyntaxError => ex
+      raise LinterLoadError,
+            "Unable to load linter file '#{path}': #{ex.message}"
+    end
+  end
+end

data/lib/lint_trappings/linter_plugin.rb

@@ -0,0 +1,35 @@
+module LintTrappings
+  # Represents a collection of linters/configuration which are loaded from a
+  # gem.
+  #
+  # This is just a wrapper to make accessing files in the gem easier.
+  class LinterPlugin
+    # @param require_path [String] name of the gem (must be the same as the path
+    #   to `require`!)
+    def initialize(require_path)
+      @require_path = require_path
+    end
+
+    def load
+      require @require_path
+    rescue LoadError, SyntaxError => ex
+      raise LinterLoadError,
+            "Unable to load linter plugin at path '#{@require_path}': #{ex.message}"
+    end
+
+    # Returns path to the configuration file that ships with this linter plugin.
+    #
+    # Note that this may not exist if no configuration is shipped with the gem.
+    #
+    # @return [String]
+    def config_file_path
+      File.join(gem_dir, 'config.yaml')
+    end
+
+    private
+
+    def gem_dir
+      Gem::Specification.find_by_name(@require_path).gem_dir
+    end
+  end
+end

data/lib/lint_trappings/linter_selector.rb

@@ -0,0 +1,120 @@
+module LintTrappings
+  # Chooses the appropriate linters to run against a file.
+  #
+  # All linter inclusion/exclusion based on command line flags or configuration
+  # is handled here. This is utilized by the runner to generate linter/file
+  # tuples representing jobs to execute (i.e. run the linter X against file Y).
+  class LinterSelector
+    # @param application [LintTrappings::Application]
+    # @param config [LintTrappings::Configuration]
+    # @param options [Hash]
+    #
+    # @raise [LintTrappings::NoLintersError] when no linters are enabled
+    def initialize(application, config, options)
+      @application = application
+      @config = config
+      @options = options
+
+      # Pre-compute this as it is expensive to calculate and used many times.
+      # This forces any errors in the configuration to be surfaced ahead of time.
+      @enabled_linter_classes = enabled_linter_classes
+    end
+
+    # Return all loaded linter classes for this application.
+    # @return [Array<Class>]
+    def all_linter_classes
+      @application.linter_base_class.descendants
+    end
+
+    # Returns initialized linter instances to run against a given file.
+    #
+    # @param path [String]
+    #
+    # @return [Array<LintTrappings::Linter>]
+    def linters_for_file(path)
+      @enabled_linter_classes.map do |linter_class|
+        linter_conf = @config.for_linter(linter_class)
+        next unless run_linter_on_file?(linter_conf, path)
+
+        linter_class.new(linter_conf)
+      end.compact
+    end
+
+    # Returns a list of linters that are enabled given the specified
+    # configuration and additional options.
+    #
+    # @return [Array<LintTrappings::Linter>]
+    def enabled_linter_classes
+      # Include the explicit list of linters if a list was specified
+      explicitly_included = included_linter_classes =
+        linter_classes_from_names(@options.fetch(:included_linters, []))
+
+      if included_linter_classes.empty?
+        # Otherwise use the list of enabled linters specified by the config.
+        # Note: this means that a linter which is disabled in the configuration
+        # can still be run if it is explicitly specified in `included_linters`
+        included_linter_classes = all_linter_classes.select do |linter_class|
+          linter_enabled?(linter_class)
+        end
+      end
+
+      excluded_linter_classes =
+        linter_classes_from_names(@options.fetch(:excluded_linters, []))
+
+      linter_classes = included_linter_classes - excluded_linter_classes
+
+      # Highlight conditions where all linters were filtered out, as this was
+      # likely a mistake on the user's part
+      if linter_classes.empty?
+        if explicitly_included.any?
+          raise NoLintersError,
+                'All specified linters were explicitly excluded!'
+        elsif included_linter_classes.empty?
+          raise NoLintersError,
+                'All linters are disabled. Enable some in your configuration!'
+        else
+          raise NoLintersError,
+                'All enabled linters were explicitly excluded!'
+        end
+      end
+
+      linter_classes
+    end
+
+    private
+
+    # Whether to run the given linter against the specified file.
+    #
+    # @param linter_conf [Hash]
+    # @param path [String]
+    #
+    # @return [Boolean]
+    def run_linter_on_file?(linter_conf, path)
+      if linter_conf['include'] &&
+         !Utils.any_glob_matches?(linter_conf['include'], path)
+        return false
+      end
+
+      if Utils.any_glob_matches?(linter_conf['exclude'], path)
+        return false
+      end
+
+      true
+    end
+
+    def linter_enabled?(linter_class)
+      @config.for_linter(linter_class)['enabled']
+    end
+
+    def linter_classes_from_names(linter_names)
+      linter_names.map do |linter_name|
+        begin
+          @application.linter_base_class.const_get(linter_name)
+        rescue NameError
+          raise NoSuchLinter,
+                "Linter #{linter_name} does not exist! Are you sure you spelt it correctly?"
+        end
+      end
+    end
+  end
+end