sugarcane 0.0.1

data/lib/sugarcane/cli/parser.rb

@@ -0,0 +1,191 @@
+require 'optparse'
+require 'sugarcane/default_checks'
+require 'sugarcane/cli/options'
+require 'sugarcane/version'
+
+module SugarCane
+  module CLI
+
+    # Provides a specification for the command line interface that drives
+    # documentation, parsing, and default values.
+    class Parser
+
+      # Exception to indicate that no further processing is required and the
+      # program can exit. This is used to handle --help and --version flags.
+      class OptionsHandled < RuntimeError; end
+
+      def self.parse(*args)
+        new.parse(*args)
+      end
+
+      def initialize(stdout = $stdout)
+        @stdout = stdout
+
+        add_banner
+        add_user_defined_checks
+
+        SugarCane.default_checks.each do |check|
+          add_check_options(check)
+        end
+        add_checks_shortcut
+
+        add_cane_options
+
+        add_version
+        add_help
+      end
+
+      def parse(args, ret = true)
+        parser.parse!(get_default_options + args)
+        SugarCane::CLI.default_options.merge(options)
+      rescue OptionParser::InvalidOption, OptionParser::AmbiguousOption
+        args = %w(--help)
+        ret = false
+        retry
+      rescue OptionsHandled
+        ret
+      end
+
+      def get_default_options
+        # Right now, read_options_from_file can't just be called on
+        # both because if the second one doesn't exist the defaults for
+        # non-existent values will override what's already read
+        if SugarCane::File.exists? './.sugarcane'
+          read_options_from_file './.sugarcane'
+        else
+          read_options_from_file './.cane'
+        end
+      end
+
+      def read_options_from_file(file)
+        if SugarCane::File.exists?(file)
+          SugarCane::File.contents(file).split(/\s+/m)
+        else
+          []
+        end
+      end
+
+      def add_banner
+        parser.banner = <<-BANNER
+Usage: sugarcane [options]
+
+Default options are loaded from a .sugarcane file in the current directory.
+
+BANNER
+      end
+
+      def add_user_defined_checks
+        description = "Load a Ruby file containing user-defined checks"
+        parser.on("-r", "--require FILE", description) do |f|
+          load(f)
+        end
+
+        description = "Use the given user-defined check"
+        parser.on("-c", "--check CLASS", description) do |c|
+          check = Kernel.const_get(c)
+          options[:checks] << check
+          add_check_options(check)
+        end
+        parser.separator ""
+      end
+
+      def add_check_options(check)
+        check.options.each do |key, data|
+          cli_key  = key.to_s.tr('_', '-')
+          opts     = data[1] || {}
+          variable = opts[:variable] || "VALUE"
+          defaults = opts[:default] || []
+
+          if opts[:type] == Array
+            parser.on("--#{cli_key} #{variable}", Array, data[0]) do |opts|
+              (options[key.to_sym] ||= []) << opts
+            end
+          else
+            if [*defaults].length > 0
+              add_option ["--#{cli_key}", variable], *data
+            else
+              add_option ["--#{cli_key}"], *data
+            end
+          end
+        end
+
+        parser.separator ""
+      end
+
+      def add_cane_options
+        add_option %w(--max-violations VALUE),
+          "Max allowed violations", default: 0, cast: :to_i
+
+        add_option %w(--editor PROGRAM), "Text editor to use", default: nil
+
+        add_option %w(--json),
+          "output as json", default: false
+
+        add_option %w(--report),
+          "output a report", default: false
+
+        add_option %w(--parallel),
+          "Use all processors. Slower on small projects, faster on large.",
+            cast: ->(x) { x }
+
+        add_option %w(--color),
+          "Colorize output", default: false
+
+        parser.separator ""
+      end
+
+      def add_checks_shortcut
+        description = "Apply all checks to given file"
+        parser.on("-f", "--all FILE", description) do |f|
+          # This is a bit of a hack, but provides a really useful UI for
+          # dealing with single files. Let's see how it evolves.
+          options[:abc_glob] = f
+          options[:style_glob] = f
+          options[:doc_glob] = f
+        end
+      end
+
+      def add_version
+        parser.on_tail("-v", "--version", "Show version") do
+          stdout.puts SugarCane::VERSION
+          raise OptionsHandled
+        end
+      end
+
+      def add_help
+        parser.on_tail("-h", "--help", "Show this message") do
+          stdout.puts parser
+          raise OptionsHandled
+        end
+      end
+
+      def add_option(option, description, opts={})
+        option_key = option[0].gsub('--', '').tr('-', '_').to_sym
+        default    = opts[:default]
+        cast       = opts[:cast] || ->(x) { x }
+
+        if default
+          description += " (default: %s)" % default
+        end
+
+        parser.on(option.join(' '), description) do |v|
+          options[option_key] = cast.to_proc.call(v)
+          options.delete(opts[:clobber])
+        end
+      end
+
+      def options
+        @options ||= {
+          checks: SugarCane.default_checks
+        }
+      end
+
+      def parser
+        @parser ||= OptionParser.new
+      end
+
+      attr_reader :stdout
+    end
+
+  end
+end

data/lib/sugarcane/cli.rb

@@ -0,0 +1,21 @@
+require 'sugarcane/cli/parser'
+require 'sugarcane/runner'
+require 'sugarcane/version'
+require 'sugarcane/file'
+
+module SugarCane
+  # Command line interface. This passes off arguments to the parser and starts
+  # the Cane runner
+  module CLI
+    def run(args)
+      spec = Parser.parse(args)
+      if spec.is_a?(Hash)
+        SugarCane.run(spec)
+      else
+        spec
+      end
+    end
+    module_function :run
+
+  end
+end

data/lib/sugarcane/default_checks.rb

@@ -0,0 +1,17 @@
+require 'sugarcane/abc_check'
+require 'sugarcane/style_check'
+require 'sugarcane/doc_check'
+require 'sugarcane/threshold_check'
+
+# Default checks performed when no checks are provided
+module SugarCane
+  def default_checks
+    [
+      AbcCheck,
+      StyleCheck,
+      DocCheck,
+      ThresholdCheck
+    ]
+  end
+  module_function :default_checks
+end

data/lib/sugarcane/doc_check.rb

@@ -0,0 +1,156 @@
+require 'sugarcane/file'
+require 'sugarcane/task_runner'
+
+module SugarCane
+
+  # Creates violations for class definitions that do not have an explantory
+  # comment immediately preceding.
+  class DocCheck < Struct.new(:opts)
+
+    DESCRIPTION =
+    "Class and Module definitions require explanatory comments on previous line"
+
+    ClassDefinition = Struct.new(:values) do
+      def line; values.fetch(:line); end
+      def label; values.fetch(:label); end
+      def missing_doc?; !values.fetch(:has_doc); end
+      def requires_doc?; values.fetch(:requires_doc, false); end
+      def requires_doc=(value); values[:requires_doc] = value; end
+    end
+
+    def self.key; :doc; end
+    def self.name; "documentation checking"; end
+    def self.options
+      {
+        doc_glob:    ['Glob to run doc checks over',
+                        default:  '{app,lib}/**/*.rb',
+                        variable: 'GLOB',
+                        clobber:  :no_doc],
+        doc_exclude: ['Exclude file or glob from documentation checking',
+                        variable: 'GLOB',
+                        type: Array,
+                        default: [],
+                        clobber: :no_doc],
+        no_readme:   ['Disable readme checking', cast: ->(x) { !x }],
+        no_doc:      ['Disable documentation checking', cast: ->(x) { !x }]
+      }
+    end
+
+    # Stolen from ERB source, amended to be slightly stricter to work around
+    # some known false positives.
+    MAGIC_COMMENT_REGEX =
+      %r"#(\s+-\*-)?\s+(en)?coding\s*[=:]\s*([[:alnum:]\-_]+)"
+
+    CLASS_REGEX = /^\s*(?:class|module)\s+([^\s;]+)/
+
+    # http://rubular.com/r/53BapkefdD
+    SINGLE_LINE_CLASS_REGEX =
+      /^\s*(?:class|module).*;\s*end\s*(#.*)?\s*$/
+
+    METHOD_REGEX = /(?:^|\s)def\s+/
+
+    def violations
+      return [] if opts[:no_doc]
+
+      missing_file_violations + worker.map(file_names) {|file_name|
+        find_violations(file_name)
+      }.flatten
+    end
+
+    def find_violations(file_name)
+      class_definitions_in(file_name).map do |class_definition|
+        if class_definition.requires_doc? && class_definition.missing_doc?
+          {
+            file:        file_name,
+            line:        class_definition.line,
+            label:       class_definition.label,
+            description: DESCRIPTION,
+            menu_description: "#{class_definition.label} requires explanatory "\
+                               "comments on the previous line"
+          }
+        end
+      end.compact
+    end
+
+    def class_definitions_in(file_name)
+      closed_classes = []
+      open_classes = []
+      last_line = ""
+
+      SugarCane::File.iterator(file_name).each_with_index do |line, number|
+        if class_definition? line
+          if single_line_class_definition? line
+            closed_classes
+          else
+            open_classes
+          end.push class_definition(number, line, last_line)
+
+        elsif method_definition?(line) && !open_classes.empty?
+          open_classes.last.requires_doc = true
+        end
+
+        last_line = line
+      end
+
+      (closed_classes + open_classes).sort_by(&:line)
+    end
+
+    def class_definition(number, line, last_line)
+      ClassDefinition.new({
+        line: (number + 1),
+        label: extract_class_name(line),
+        has_doc: comment?(last_line),
+        requires_doc: method_definition?(line)
+      })
+    end
+
+    def missing_file_violations
+      result = []
+      return result if opts[:no_readme]
+
+      if SugarCane::File.case_insensitive_glob("README*").none?
+        result << { description: 'Missing documentation',
+                    label: 'No README found' }
+      end
+      result
+    end
+
+    def file_names
+      Dir[opts.fetch(:doc_glob)].reject { |file| excluded?(file) }
+    end
+
+    def method_definition?(line)
+      line =~ METHOD_REGEX
+    end
+
+    def class_definition?(line)
+      line =~ CLASS_REGEX && $1.index('<<') != 0
+    end
+
+    def single_line_class_definition?(line)
+      line =~ SINGLE_LINE_CLASS_REGEX
+    end
+
+    def comment?(line)
+      line =~ /^\s*#/ && !(MAGIC_COMMENT_REGEX =~ line)
+    end
+
+    def extract_class_name(line)
+      line.match(CLASS_REGEX)[1]
+    end
+
+    def exclusions
+      @exclusions ||= opts.fetch(:doc_exclude, []).flatten.map do |i|
+        Dir[i]
+      end.flatten.to_set
+    end
+
+    def excluded?(file)
+      exclusions.include?(file)
+    end
+
+    def worker
+      SugarCane.task_runner(opts)
+    end
+  end
+end

data/lib/sugarcane/encoding_aware_iterator.rb

@@ -0,0 +1,30 @@
+module SugarCane
+
+  # Provides iteration over lines (from a file), correctly handling encoding.
+  class EncodingAwareIterator
+    include Enumerable
+
+    def initialize(lines)
+      @lines = lines
+    end
+
+    def each(&block)
+      return self.to_enum unless block
+
+      lines.each do |line|
+        begin
+          line =~ /\s/
+        rescue ArgumentError
+          line.encode!('UTF-8', 'binary', invalid: :replace, undef: :replace)
+        end
+
+        block.call(line)
+      end
+    end
+
+    protected
+
+    attr_reader :lines
+  end
+
+end

data/lib/sugarcane/ext/array.rb

@@ -0,0 +1,24 @@
+# Adapted from https://github.com/flyerhzm/code_analyzer
+# License: MIT
+class Array
+  def line_number
+    case self[0]
+    when :def, :defs, :command, :command_call, :call, :fcall, :method_add_arg,
+         :method_add_block, :var_ref, :vcall, :const_ref, :const_path_ref,
+         :class, :module, :if, :unless, :elsif, :ifop, :if_mod, :unless_mod,
+         :binary, :alias, :symbol_literal, :symbol, :aref, :hash, :assoc_new,
+         :string_literal, :massign
+      self[1].line_number
+    when :assoclist_from_args, :bare_assoc_hash
+      self[1][0].line_number
+    when :string_add, :opassign
+      self[2].line_number
+    when :array
+      array_values.first.line_number
+    when :mlhs_add
+      self.last.line_number
+    else
+      self.last.first if self.last.is_a? Array
+    end
+  end
+end

data/lib/sugarcane/file.rb

@@ -0,0 +1,30 @@
+require 'sugarcane/encoding_aware_iterator'
+
+module SugarCane
+
+  # An interface for interacting with files that ensures encoding is handled in
+  # a consistent manner.
+  class File
+    class << self
+      def iterator(path)
+        EncodingAwareIterator.new(open(path).each_line)
+      end
+
+      def contents(path)
+        open(path).read
+      end
+
+      def open(path)
+        ::File.open(path, 'r:utf-8')
+      end
+
+      def exists?(path)
+        ::File.exists?(path)
+      end
+
+      def case_insensitive_glob(glob)
+        Dir.glob(glob, ::File::FNM_CASEFOLD)
+      end
+    end
+  end
+end

data/lib/sugarcane/json_formatter.rb

@@ -0,0 +1,17 @@
+require 'json'
+
+module SugarCane
+
+  # Computes a machine-readable JSON representation from an array of violations
+  # computed by the checks.
+  class JsonFormatter
+    def initialize(violations, options = {})
+      @violations = violations
+    end
+
+    def to_s
+      @violations.to_json
+    end
+  end
+
+end