lint_trappings 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: e033fd62166d774b4a18cc1c1a05713f194c22b7
+  data.tar.gz: 95160b22578c977eb2ed213c1ffd9ed665b5f4cd
+SHA512:
+  metadata.gz: 5d917e31b883e44ca39cf96f02190242a321801bb1d72ca72643018930f07e83d27bbc60193a88d92c166cc257b94a33af381fe1b39a488066fef7c115627f22
+  data.tar.gz: b6134bc6b4559a063ba496fae837517e5c8f36fa46ea7f2a2f07a85944f5376151136291e909fa6cc95fe715b43264e7179dc77f97c01607bbb88202ea7c879e

data/LICENSE.md

@@ -0,0 +1,21 @@
+LintTrappings is released under the MIT license.
+
+> Copyright (c) 2016 Shane da Silva. http://shane.io
+>
+> Permission is hereby granted, free of charge, to any person obtaining a copy
+> of this software and associated documentation files (the "Software"), to deal
+> in the Software without restriction, including without limitation the rights
+> to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+> copies of the Software, and to permit persons to whom the Software is
+> furnished to do so, subject to the following conditions:
+>
+> The above copyright notice and this permission notice shall be included in
+> all copies or substantial portions of the Software.
+>
+> THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+> IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+> FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+> AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+> LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+> OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+> SOFTWARE.

data/lib/lint_trappings.rb

@@ -0,0 +1,17 @@
+# Load all modules necessary to work with the framework.
+# Ordering here can be important depending on class references in each module.
+
+require 'lint_trappings/errors'
+require 'lint_trappings/configuration'
+require 'lint_trappings/utils'
+require 'lint_trappings/file_finder'
+require 'lint_trappings/output'
+require 'lint_trappings/document'
+require 'lint_trappings/location'
+require 'lint_trappings/lint'
+require 'lint_trappings/linter'
+require 'lint_trappings/linter_loader'
+require 'lint_trappings/linter_selector'
+require 'lint_trappings/report'
+require 'lint_trappings/runner'
+require 'lint_trappings/application'

data/lib/lint_trappings/application.rb

@@ -0,0 +1,138 @@
+require 'lint_trappings/errors'
+require 'lint_trappings/configuration_loader'
+require 'lint_trappings/configuration_resolver'
+
+module LintTrappings
+  # Linter application superclass.
+  #
+  # Implementors will subclass this and specify a number of high-level
+  # configuration options which will help the class run your custom application.
+  #
+  # @abstract
+  class Application
+    # Define an application configuration attribute.
+    #
+    # This is intended to be used to make specifying the configuration for a
+    # LintTrappings application easy. It defines a class instance variable which is
+    # specified in the body of the class itself via DSL-like method call, and
+    # also defines a method so the value can be obtained from a single instance.
+    def self.class_attribute(attr_name)
+      # Define DSL getter/setter
+      metaclass = (class << self; self; end)
+      metaclass.instance_eval do
+        define_method(attr_name) do |*args|
+          if args.any?
+            instance_variable_set(:"@#{attr_name}", args.first)
+          else
+            value = instance_variable_get(:"@#{attr_name}")
+
+            if value.nil?
+              raise ApplicationConfigurationError,
+                    "`#{attr_name}` class attribute must be defined in #{self}!"
+            end
+
+            value
+          end
+        end
+      end
+
+      # Define method on the class
+      define_method(attr_name) do
+        self.class.send(attr_name)
+      end
+    end
+
+    # @return [String] Proper name of this application
+    class_attribute :name
+
+    # @return [String] Name of the application executable
+    class_attribute :executable_name
+
+    # @return [String] Application version
+    class_attribute :version
+
+    # @return [LintTrappings::Configuration] Base configuration which all other
+    #   configurations extend (can be empty if desired). This should be the same
+    #   class as the configuration_class attribute.
+    class_attribute :base_configuration
+
+    # @return [String] Configuration file names to look for, in order of
+    #   precedence (first one found wins)
+    class_attribute :configuration_file_names
+
+    # @return [String] List of file extensions the application can lint
+    class_attribute :file_extensions
+
+    # @return [String] URL of the application's home page
+    class_attribute :home_url
+
+    # @return [String] URL of the application's issue and bug reports page
+    class_attribute :issues_url
+
+    # @return [String] Directory prefix where gem stores built-in linters
+    class_attribute :linters_directory
+
+    # @return [Class] Base class of all linters for this application
+    class_attribute :linter_base_class
+
+    # @return [Class] Class to use when loading/parsing documents
+    class_attribute :document_class
+
+    # @param output [LintTrappings::Output]
+    def initialize(output)
+      @output = output
+    end
+
+    def run(options = {})
+      @output.color_enabled = options.fetch(:color, @output.tty?)
+      config = load_configuration(options)
+
+      command = create_command(options[:command]).new(self, config, options, @output)
+      command.run
+    end
+
+    private
+
+    def create_command(command)
+      raise InvalidCommandError,
+            '`command` option must be specified!' unless command
+
+      command = command.to_s
+
+      require 'lint_trappings/command/base'
+      begin
+        require "lint_trappings/command/#{Utils.snake_case(command)}"
+      rescue LoadError, SyntaxError => ex
+        raise InvalidCommandError,
+              "Unable to load command '#{command}': #{ex.message}"
+      end
+
+      Command.const_get(Utils.camel_case(command))
+    end
+
+    # Loads the application configuration.
+    #
+    # @param options [Hash]
+    #
+    # @return [LintTrappings::Configuration]
+    def load_configuration(options)
+      config_loader = ConfigurationLoader.new(self)
+
+      config =
+        if options[:config_file]
+          config_loader.load_file(options[:config_file])
+        else
+          begin
+            config_loader.load(working_directory: Dir.pwd)
+          rescue NoConfigurationFileError
+            base_configuration
+          end
+        end
+
+      config = ConfigurationResolver.new(config_loader).resolve(config, options)
+
+      # Always extend the base/default configuration
+      base_configuration.merge(config)
+    end
+  end
+end

data/lib/lint_trappings/arguments_parser.rb

@@ -0,0 +1,145 @@
+require 'optparse'
+
+module LintTrappings
+  # Handles option parsing for the command line application.
+  class ArgumentsParser
+    def initialize(application)
+      @application = application
+    end
+
+    # 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 = {}
+      @options[:command] = :scan # Default command is to scan for lints
+
+      OptionParser.new do |parser|
+        parser.banner = "Usage: #{@application.executable_name} [options] [file1, file2, ...]"
+
+        add_linter_options parser
+        add_file_options parser
+        add_misc_options parser
+        add_info_options parser
+      end.parse!(args)
+
+      # Any remaining arguments are assumed to be files that should be linted
+      @options[:included_paths] = args
+
+      @options
+    rescue OptionParser::InvalidOption => ex
+      raise InvalidCliOptionError,
+            "#{ex.message}\nRun `#{@application.executable_name} --help` to " \
+            'see a list of available options.'
+    end
+
+    private
+
+    # 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|
+        @options[:config_file] = conf_file
+      end
+
+      parser.on('-e', '--exclude-path file', String,
+                'List of file paths to exclude') do |file_path|
+        (@options[:excluded_paths] ||= []) << file_path
+      end
+
+      parser.on('-f', '--format formatter-name', String,
+                'Specify which output format you want') do |formatter_name|
+        (@options[:formatters] ||= []) << {
+          formatter_name => :stdout,
+        }
+      end
+
+      parser.on('-o', '--out output-file-path', String,
+                'Specify a file to write output to') do |file_path|
+        if @options[:formatters]
+          # Change the last specified formatter to output to the given file
+          last_formatter = @options[:formatters].last
+          last_formatter[last_formatter.keys.first] = file_path
+        else
+          # Otherwise if no formatters have been specified yet, set the default
+          # formatter to write to the given file
+          @options[:formatters] << { 'Default' => file_path }
+        end
+      end
+
+      parser.on('--stdin-file-path file-path', String,
+                'Specify the path name for the file passed via STDIN') do |file_path|
+        @options[:stdin] = STDIN
+        @options[:stdin_file_path] = file_path
+      end
+
+      parser.on('-r', '--require require-path', String,
+                'Specify a path to `require`') do |require_path|
+        (@options[:require_paths] ||= []) << require_path
+      end
+    end
+
+    # Register linter-related flags.
+    def add_linter_options(parser)
+      parser.on('-i', '--include-linter linter', String,
+                'Specify which linters you want to run ' \
+                '(overrides those in your configuration)') do |linter|
+        (@options[:included_linters] ||= []).concat(linter.split(/\s*,\s*/))
+      end
+
+      parser.on('-x', '--exclude-linter linter', String,
+                "Specify which linters you don't want to run " \
+                '(in addition to those disabled by your configuration)') do |linter|
+        (@options[:excluded_linters] ||= []).concat(linter.split(/\s*,\s*/))
+      end
+    end
+
+    def add_misc_options(parser)
+      parser.on('-C', '--concurrency workers', Integer,
+                'Specify the number of concurrent workers you want') do |workers|
+        @options[:concurrency] = workers
+      end
+    end
+
+    # Register informational flags.
+    def add_info_options(parser)
+      parser.on('--show-linters',
+                'Display available linters and whether or not they are enabled') do
+        @options[:command] = :display_linters
+      end
+
+      parser.on('--show-formatters', 'Display available formatters') do
+        @options[:command] = :display_formatters
+      end
+
+      parser.on('--show-docs [linter-name]', '--show-documentation [linter-name]') do |linter_name|
+        @options[:command] = :display_documentation
+        @options[:linter] = linter_name
+      end
+
+      parser.on('--[no-]color', 'Force output to be colorized') do |color|
+        @options[:color] = color
+      end
+
+      parser.on('-d', '--debug', 'Enable debug mode for more verbose output') do
+        @options[:debug] = true
+      end
+
+      parser.on_tail('-h', '--help', 'Display help documentation') do
+        @options[:command] = :display_help
+        @options[:help_message] = parser.help
+      end
+
+      parser.on_tail('-v', '--version', 'Display version') do
+        @options[:command] = :display_version
+      end
+
+      parser.on_tail('-V', '--verbose-version', 'Display verbose version information') do
+        @options[:command] = :display_version
+        @options[:verbose_version] = true
+      end
+    end
+  end
+end

data/lib/lint_trappings/cli.rb

@@ -0,0 +1,61 @@
+require 'lint_trappings'
+require 'lint_trappings/arguments_parser'
+
+module LintTrappings
+  # Command line application interface.
+  class Cli
+    # @param application [LintTrappings::Application]
+    # @param output [LintTrappings::Output] stderr stream
+    def initialize(application, output)
+      @application = application
+      @output = output
+    end
+
+    # Parses the given command line arguments and executes appropriate logic
+    # based on those arguments.
+    #
+    # @param args [Array<String>] command line arguments
+    #
+    # @return [Integer] exit status code
+    def run(args)
+      options = ArgumentsParser.new(@application).parse(args)
+      @application.run(options)
+      0 # OK
+    rescue ScanWarned, ScanFailed => ex
+      # Special errors which we don't want to display, but do want their exit status
+      ex.exit_status
+    rescue => ex
+      handle_exception(ex)
+    end
+
+    private
+
+    # Returns an appropriate error code for the specified exception, and outputs
+    # a message if necessary.
+    def handle_exception(ex)
+      if ex.is_a?(LintTrappings::LintTrappingsError) && ex.exit_status != 70
+        @output.error ex.message
+        ex.exit_status
+      else
+        print_unexpected_exception(ex)
+        ex.respond_to?(:exit_status) ? ex.exit_status : 70
+      end
+    end
+
+    # Outputs the backtrace of an exception with instructions on how to report
+    # the issue.
+    def print_unexpected_exception(ex)
+      @output.bold_error ex.message
+      @output.error ex.backtrace.join("\n")
+      @output.warning 'Report this bug at ', false
+      @output.info @application.issues_url
+      @output.newline
+      @output.success 'To help fix this issue, please include:'
+      @output.puts '- The above stack trace'
+      @output.print "- #{@application.name} version: "
+      @output.info @application.version
+      @output.print '- Ruby version: '
+      @output.info RUBY_VERSION
+    end
+  end
+end

data/lib/lint_trappings/command/base.rb

@@ -0,0 +1,36 @@
+module LintTrappings::Command
+  # Abstract base class of all commands.
+  #
+  # @abstract
+  class Base
+    # @param application [LintTrappings::Application]
+    # @param config [LintTrappings::Configuration]
+    # @param options [Hash]
+    # @param output [LintTrappings::Output]
+    def initialize(application, config, options, output)
+      @application = application
+      @config = config
+      @options = options
+      @output = output
+    end
+
+    # Runs the command.
+    def run
+      raise NotImplementedError, 'Define `execute` in `Command::Base` subclass'
+    end
+
+    private
+
+    # @return [LintTrappings::Application]
+    attr_reader :application
+
+    # @return [LintTrappings::Configuration]
+    attr_reader :config
+
+    # @return [Hash]
+    attr_reader :options
+
+    # @return [LintTrappings::Output]
+    attr_reader :output
+  end
+end

data/lib/lint_trappings/command/display_documentation.rb

@@ -0,0 +1,65 @@
+require 'terminal-table'
+
+module LintTrappings::Command
+  # Displays documentation for the specified linter
+  class DisplayDocumentation < Base
+    def run
+      LintTrappings::LinterLoader.new(application, config).load(options)
+
+      output.info 'Linter Documentation'
+      output.info '--------------------'
+
+      linter_classes(options).sort_by(&:canonical_name).each do |linter_class|
+        display_linter_doc(linter_class)
+      end
+    end
+
+    private
+
+    def display_linter_doc(linter_class)
+      output.newline
+      output.notice linter_class.canonical_name
+      output.puts linter_class.description
+      output.newline
+
+      return unless linter_class.options.any?
+
+      table = Terminal::Table.new do |t|
+        t << %w[Option Description Type Default]
+
+        t.add_separator
+
+        linter_class.options.each do |option_name, option_spec|
+          t << [
+            option_name,
+            option_spec[:description],
+            option_spec[:type],
+            display_value(option_spec[:default]),
+          ]
+        end
+      end
+
+      output.puts table.to_s
+    end
+
+    def display_value(value)
+      if value.is_a?(Array)
+        value.map { |v| "- #{v}" }.join("\n")
+      else
+        value
+      end
+    end
+
+    def linter_classes(options)
+      if options[:linter]
+        begin
+          [application.linter_base_class.const_get(options[:linter])]
+        rescue NameError
+          raise NoSuchLinter, "No linter named #{options[:linter]} exists!"
+        end
+      else
+        application.linter_base_class.descendants
+      end
+    end
+  end
+end