lint_trappings 0.1.0

data/lib/lint_trappings/executable.rb

@@ -0,0 +1,26 @@
+require 'lint_trappings/cli'
+
+# Helper module for creating a LintTrappings-powered executable.
+module LintTrappings::Executable
+  module_function
+
+  # Runs the command line interface.
+  #
+  # This should be called from your application executable, like so:
+  #
+  # @example
+  #   #!/usr/bin/env ruby
+  #   require 'my_linter_gem'
+  #   require 'lint_trappings/executable'
+  #   LintTrappings::Executable.run(MyLinter::Application, STDOUT, STDERR, ARGV)
+  #
+  # @param application_class [Class]
+  # @param stdout [IO] output stream
+  # @param arguments [Array<String>] command line arguments
+  def run(application_class, stdout, stderr, arguments)
+    output = LintTrappings::Output.new(stdout)
+    error_output = LintTrappings::Output.new(stderr)
+    application = application_class.new(output)
+    exit LintTrappings::Cli.new(application, error_output).run(arguments)
+  end
+end

data/lib/lint_trappings/file_finder.rb

@@ -0,0 +1,171 @@
+require 'find'
+
+module LintTrappings
+  # Finds files that should be linted.
+  module FileFinder
+    class << self
+      # Return list of lintable files given the specified set of paths and glob
+      # pattern search criteria.
+      #
+      # The distinction between paths and globs is so files with a `*` in their
+      # name can still be matched if necessary without treating them as a glob
+      # pattern.
+      #
+      # @param options [Hash]
+      # @option options :included_paths [Array<String>] files/directories to include
+      # @option options :excluded_paths [Array<String>] files/directories to exclude
+      # @option options :included_patterns [Array<String>] glob patterns to include
+      # @option options :excluded_patterns [Array<String>] glob patterns to exclude
+      # @option options :file_extensions [Array<String>] extensions of files to
+      #   include when searching directories specified by included_paths
+      #
+      # @raise [InvalidFilePathError] if included_paths/excluded_paths don't exist
+      # @raise [InvalidFilePatternError] if any included_pattern doesn't match any files
+      #
+      # @return [Array<String>] list of matching files in lexicographic order
+      def find(options)
+        included_paths = options.fetch(:included_paths, []).map { |p| normalize_path(p) }
+        excluded_paths = options.fetch(:excluded_paths, []).map { |p| normalize_path(p) }
+        included_patterns = options.fetch(:included_patterns, []).map { |p| normalize_path(p) }
+        excluded_patterns = options.fetch(:excluded_patterns, []).map { |p| normalize_path(p) }
+        allowed_extensions = options.fetch(:allowed_extensions)
+
+        included_files = expand_paths(included_paths, included_patterns, allowed_extensions)
+        matching_files = filter_files(included_files, excluded_paths, excluded_patterns)
+
+        matching_files.uniq.sort
+      end
+
+      private
+
+      # Expand included paths to include lintable files under paths which are
+      # directories.
+      #
+      # @param paths [Array<String>]
+      # @param patterns [Array<String>]
+      # @param allowed_extensions [Array<String>]
+      #
+      # @return [Array<String>]
+      def expand_paths(paths, patterns, allowed_extensions)
+        find_files_in_paths(paths, allowed_extensions) + find_matching_files(patterns)
+      end
+
+      # Exclude specified files from the list of included files, expanding the
+      # excluded paths as necessary.
+      #
+      # @param included_paths [Array<String>]
+      # @param excluded_paths [Array<String>]
+      # @param excluded_patterns [Array<String>]
+      #
+      # @return [Array<String>]
+      def filter_files(included_files, excluded_paths, excluded_patterns)
+        # Convert excluded paths to patterns so we don't need to actually hold
+        # all excluded files in memory
+        excluded_patterns = excluded_patterns.dup
+        excluded_paths.each do |file|
+          if File.directory?(file)
+            excluded_patterns << File.join(file, '**', '*')
+          elsif File.file?(file)
+            excluded_patterns << file
+          else
+            raise LintTrappings::InvalidFilePathError,
+                  "Excluded path '#{path}' does not correspond to a valid file"
+          end
+        end
+
+        included_files.reject do |file|
+          LintTrappings::Utils.any_glob_matches?(excluded_patterns, file)
+        end
+      end
+
+      # Search the specified paths for lintable files.
+      #
+      # If path is a directory, searches the directory recursively.
+      #
+      # @param paths [Array<String>]
+      # @param allowed_extensions [Array<String>]
+      #
+      # @return [Array<String>]
+      def find_files_in_paths(paths, allowed_extensions)
+        files = []
+
+        paths.each do |path|
+          if File.directory?(path)
+            files += find_files_in_directory(path, allowed_extensions)
+          elsif File.file?(path)
+            files << path
+          else
+            raise LintTrappings::InvalidFilePathError,
+                  "Path '#{path}' does not correspond to a valid file or directory"
+          end
+        end
+
+        files.uniq.map { |path| normalize_path(path) }
+      end
+
+      # Recursively search the specified directory for lintable files.
+      #
+      # @param directory [String]
+      # @param allowed_extensions [Array<String>]
+      #
+      # @return [Array<String>]
+      def find_files_in_directory(directory, allowed_extensions)
+        files = []
+
+        ::Find.find(directory) do |path|
+          files << path if lintable_file?(path, allowed_extensions)
+        end
+
+        files
+      end
+
+      # Find all files matching the specified glob patterns.
+      #
+      # @param patterns [Array<String>] glob patterns
+      #
+      # @return [Array<String>]
+      def find_matching_files(patterns)
+        files = []
+
+        patterns.each do |pattern|
+          matches = ::Dir.glob(pattern,
+                               ::File::FNM_PATHNAME | # Wildcards don't match path separators
+                               ::File::FNM_DOTMATCH)  # `*` wildcard matches dotfiles
+
+          if matches.empty?
+            # One of the patterns specified does not match anything; raise a more
+            # descriptive exception so we know which one
+            raise LintTrappings::InvalidFilePatternError,
+                  "Glob pattern '#{pattern}' does not match any file"
+          end
+
+          matches.each do |path|
+            files << path if File.file?(path)
+          end
+        end
+
+        files.flatten.uniq.map { |path| normalize_path(path) }
+      end
+
+      # Trim "./" from the front of relative paths.
+      #
+      # @param path [String]
+      #
+      # @return [String]
+      def normalize_path(path)
+        path.start_with?(".#{File::SEPARATOR}") ? path[2..-1] : path
+      end
+
+      # Whether a file should be treated as lintable.
+      #
+      # @param file [String]
+      # @param allowed_extensions [Array<String>]
+      #
+      # @return [Boolean]
+      def lintable_file?(file, allowed_extensions)
+        return false unless ::File.file?(file)
+        allowed_extensions.include?(::File.extname(file))
+      end
+    end
+  end
+end

data/lib/lint_trappings/formatter/base.rb

@@ -0,0 +1,67 @@
+module LintTrappings::Formatter
+  # Abstract lint formatter. Subclass and override {#display_report} to
+  # implement a custom formatter.
+  #
+  # @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
+
+      # Used in helpers to determine if severity should be displayed as failure
+      # or not
+      severities = @config.fetch('severities', error: 'fail', warning: 'warn')
+      @fail_severities = severities.select { |_severity, action| action == 'fail' }.keys
+      @warn_severities = severities.select { |_severity, action| action == 'warn' }.keys
+    end
+
+    # Called at the start of the run once runner has determined all files it
+    # will lint.
+    def started(_files_to_lint)
+    end
+
+    # Called at the beginning of a job for a linter run against a file.
+    #
+    # This can be called in parallel.
+    def job_started(_job)
+    end
+
+    # Called at the end of a job for a linter run against a file.
+    #
+    # This can be called in parallel.
+    def job_finished(_job, _lints)
+    end
+
+    # Called at the end of the run.
+    def finished(_report)
+    end
+
+    private
+
+    # @return [LintTrappings::Application]
+    attr_reader :application
+
+    # @return [LintTrappings::Configuration]
+    attr_reader :config
+
+    # @return [Hash]
+    attr_reader :options
+
+    # @return [LintTrappings::Output] stream to send output to
+    attr_reader :output
+
+    def failing_lint?(lint)
+      @fail_severities.include?(lint.severity)
+    end
+
+    def warning_lint?(lint)
+      @warn_severities.include?(lint.severity)
+    end
+  end
+end

data/lib/lint_trappings/formatter/checkstyle.rb

@@ -0,0 +1,34 @@
+require 'lint_trappings/formatter/base'
+require 'stringio'
+
+module LintTrappings::Formatter
+  # Outputs results in a Checkstyle-compatible format.
+  #
+  # @see http://checkstyle.sourceforge.net/
+  class Checkstyle < Base
+    def finished(report)
+      xml = StringIO.new
+      xml << "<?xml version=\"1.0\" encoding=\"utf-8\"?>\n"
+
+      xml << "<checkstyle version=\"1.5.6\">\n"
+      report.lints.group_by(&:path).each do |path, lints|
+        file_name_absolute = File.expand_path(path)
+        xml << "  <file name=#{file_name_absolute.encode(xml: :attr)}>\n"
+
+        lints.each do |lint|
+          xml << "    <error source=\"#{lint.linter.canonical_name if lint.linter}\" " \
+             "line=\"#{lint.location.line}\" " \
+             "column=\"#{lint.location.column}\" " \
+             "length=\"#{lint.location.length}\" " \
+             "severity=\"#{lint.severity}\" " \
+             "message=#{lint.message.encode(xml: :attr)} />\n"
+        end
+
+        xml << "  </file>\n"
+      end
+      xml << "</checkstyle>\n"
+
+      output.print xml.string
+    end
+  end
+end

data/lib/lint_trappings/formatter/default.rb

@@ -0,0 +1,99 @@
+require 'lint_trappings/formatter/base'
+
+module LintTrappings::Formatter
+  # Outputs lints in a simple format with the filename, line number, and lint
+  # message.
+  class Default < Base
+    def started(files_to_lint)
+      files = LintTrappings::Utils.pluralize('file', files_to_lint.count)
+      output.info "Scanning #{files_to_lint.count} #{files}..."
+    end
+
+    def job_finished(_job, lints)
+      @at_least_one_job_finished = true
+
+      if lints.any? { |lint| failing_lint?(lint) }
+        output.error 'F', false
+      elsif lints.any? { |lint| warning_lint?(lint) }
+        output.warning 'W', false
+      else
+        output.success '.', false
+      end
+    end
+
+    def finished(report)
+      # Ensure we have a newline after the last progress dot output
+      output.newline if @at_least_one_job_finished
+
+      report.lints.each do |lint|
+        print_location(lint)
+        print_message(lint)
+      end
+
+      output.newline
+
+      files = LintTrappings::Utils.pluralize('file', report.documents_inspected.count)
+      output.print "#{report.documents_inspected.count} #{files} inspected"
+
+      if report.failures?
+        failures = LintTrappings::Utils.pluralize('failure', report.failures.count)
+        output.print ', '
+        output.error "#{report.failures.count} #{failures} reported", false
+      end
+
+      if report.warnings?
+        warnings = LintTrappings::Utils.pluralize('warning', report.warnings.count)
+        output.print ', '
+        output.warning "#{report.warnings.count} #{warnings} reported", false
+      end
+
+      if report.success?
+        output.print ', '
+        output.success 'no issues reported', false
+      end
+
+      output.newline
+    end
+
+    private
+
+    def print_location(lint)
+      output.info lint.path, false
+      output.puts ':', false
+      output.bold lint.source_range.begin.line, false
+      output.print ':'
+      output.bold lint.source_range.begin.column, false
+      output.print ' '
+    end
+
+    def print_message(lint)
+      if failing_lint?(lint)
+        output.error severity_character(lint.severity), false
+      elsif warning_lint?(lint)
+        output.warning severity_character(lint.severity), false
+      end
+
+      if lint.linter
+        output.notice("[#{lint.linter.canonical_name}] ", false)
+      end
+
+      message = lint.message
+      if lint.exception
+        message << ' (specify --debug flag to see backtrace)' unless options[:debug]
+      end
+      output.puts message
+
+      print_exception(lint)
+    end
+
+    def print_exception(lint)
+      return unless lint.exception && options[:debug]
+      output.error "#{lint.exception.class}: #{lint.exception.message}"
+      output.error lint.exception.backtrace.join("\n")
+    end
+
+    def severity_character(severity)
+      "#{severity.to_s[0].capitalize} "
+    end
+  end
+end

data/lib/lint_trappings/formatter/json.rb

@@ -0,0 +1,62 @@
+require 'lint_trappings/formatter/base'
+require 'json'
+
+module LintTrappings::Formatter
+  # Outputs report as a JSON document.
+  class JSON < Base
+    def finished(report)
+      lints = report.lints
+      grouped = lints.group_by(&:path)
+
+      report_hash = {
+        metadata: metadata,
+        files: grouped.map { |path, lints_for_path| path_hash(path, lints_for_path) },
+        summary: {
+          offense_count: lints.count,
+          offending_file_count: grouped.count,
+          inspected_file_count: report.documents_inspected.count,
+        },
+      }
+
+      output.puts ::JSON.pretty_generate(report_hash)
+    end
+
+    private
+
+    def metadata
+      {
+        linter_version:   @application.version,
+        ruby_engine:      RUBY_ENGINE,
+        ruby_version:     RUBY_VERSION,
+        ruby_patchlevel:  RUBY_PATCHLEVEL.to_s,
+        ruby_platform:    RUBY_PLATFORM,
+      }
+    end
+
+    def path_hash(path, lints)
+      {
+        path: path,
+        offenses: lints.map { |lint| lint_hash(lint) },
+      }
+    end
+
+    def lint_hash(lint)
+      {
+        severity: lint.severity,
+        message: lint.message,
+        line: lint.source_range.begin.line,
+        column: lint.source_range.begin.column,
+        source_range: {
+          begin: {
+            line: lint.source_range.begin.line,
+            column: lint.source_range.begin.column,
+          },
+          end: {
+            line: lint.source_range.end.line,
+            column: lint.source_range.end.column,
+          },
+        },
+      }
+    end
+  end
+end