maximus 0.1.1 → 0.1.2

data/lib/maximus/lint.rb

@@ -1,27 +1,30 @@
 require 'json'
 
 module Maximus
+  # @since 0.1.0
   class Lint
     attr_accessor :output
 
     include Helper
 
-    # opts - Lint options (default: {})
-    #    :is_dev
-    #    :git_files
-    #    :root_dir
-    #    :path
-    # all lints should start with the following defined:
-    # def result method to handle the actual parsing
-    # TODO - should this be def output to be more consistent?
-    # Didn't want to trip over the instance variable @output
-    # `@task = 'name'` (__method__.to_s works fine)
-    # `@path ||= 'path/or/**/glob/to/files'` (string)
-    # they should contain the data output from the linter in JSON or
-    # JSON.parse format with the styles defined in README.md
-    # they should end with something similar to
-    # `@output[:files_inspected] ||= files_inspected(extension, delimiter, base_path_replacement)`
-    # `refine data_from_output`
+    # Perform a lint of relevant code
+    #
+    # All defined lints require a "result" method
+    # @example the result method in the child class
+    #   def result(opts = {})
+    #     @task = __method__.to_s
+    #     @path ||= 'path/or/**/glob/to/files''
+    #     lint_data = JSON.parse(`some-command-line-linter`)
+    #     @output[:files_inspected] ||= files_inspected(extension, delimiter, base_path_replacement)
+    #     refine data_from_output
+    #  end
+    #
+    # @param opts [Hash] the options to create a lint with
+    # @option opts [Boolean] :is_dev (false) whether or not the class was initialized from the command line
+    # @option opts [Array<String, Symbol>] :git_files files returned from the commit
+    # @option opts [String] :root_dir base directory
+    # @option opts [String, Array] :path ('') path to files. Accepts glob notation
+    # @return @output [Hash] combined and refined data from lint
     def initialize(opts = {})
       opts[:is_dev] ||= false
       opts[:root_dir] ||= root_dir
@@ -35,7 +38,9 @@ module Maximus
     end
 
     # Convert raw data into warnings, errors, conventions or refactors. Use this wisely.
-    # Returns complete @output as Hash
+    #
+    # @param data [Hash] unfiltered lint data
+    # @return [Hash] refined lint data and all the other bells and whistles
     def refine(data)
       # Prevent abortive empty JSON.parse error
       data = '{}' if data.blank?
@@ -77,7 +82,7 @@ module Maximus
       @output[:lint_refactors] = lint_refactors
       lint_count = (lint_errors.length + lint_warnings.length + lint_conventions.length + lint_refactors.length)
       if @@is_dev
-        lint_dev_format data unless data.blank?
+        puts lint_dev_format(data) unless data.blank?
         puts lint_summarize
         lint_ceiling lint_count
       else
@@ -92,13 +97,18 @@ module Maximus
     protected
 
     # List all files inspected
-    # Returns Array
-    def files_inspected(ext, delimiter = ',', replace = @opts[:root_dir])
-      @path.is_a?(Array) ? @path.split(delimiter) : file_list(@path, ext, replace)
+    #
+    # @param ext [String] extension to search for
+    # @param delimiter [String] comma or space separated
+    # @param remove [String] remove from all file names
+    # @return all_files [Array<string>] list of file names
+    def files_inspected(ext, delimiter = ',', remove = @opts[:root_dir])
+      @path.is_a?(Array) ? @path.split(delimiter) : file_list(@path, ext, remove)
     end
 
     # Compare lint output with lines changed in commit
-    # Returns Array of lints that match the lines in commit
+    #
+    # @return [Array] lints that match the lines in commit
     def relevant_lints(lint, files)
       all_files = {}
       files.each do |file|
@@ -112,7 +122,7 @@ module Maximus
           unless lint_file.blank?
             all_files[revert_name] = []
 
-            # TODO - originally I tried .map and delete_if, but this works,
+            # @todo originally I tried .map and delete_if, but this works,
             # and the other method didn't cover all bases.
             # Gotta be a better way to write this though
             lint_file.each do |l|
@@ -136,7 +146,8 @@ module Maximus
     private
 
     # Send abbreviated results to console or to the log
-    # Returns console message
+    #
+    # @return [String] console message to display
     def lint_summarize
       puts "\n" if @@is_dev
 
@@ -154,9 +165,12 @@ module Maximus
       success
     end
 
-    # If there's just too much to handle, through a warning. MySQL may not store everything and throw an abortive error if the blob is too large
-    # Returns prompt if lint_length is greater than 100
+    # If there's just too much to handle, through a warning.
+    # MySQL may not store all the data and throw an abortive error if the blob is too large
     # If prompt returns truthy, execution continues
+    #
+    # @param lint_length [Integer] count of how many lints
+    # @return [String] console message to display
     def lint_ceiling(lint_length)
       if lint_length > 100
         lint_dev_format
@@ -170,9 +184,12 @@ module Maximus
       end
     end
 
-    # Dev display, used for the rake task
-    # Returns console message
+    # Dev display, executed only when called from command line
+    #
+    # @param errors [Hash] data from lint
+    # @return [String] console message to display
     def lint_dev_format(errors = @output[:raw_data])
+      return if errors.blank?
       pretty_output = ''
       errors.each do |filename, error_list|
         pretty_output += "\n"
@@ -194,7 +211,7 @@ module Maximus
           pretty_output += "\n"
         end
       end
-      puts pretty_output
+      pretty_output
     end
 
   end

data/lib/maximus/lints/brakeman.rb

@@ -1,7 +1,10 @@
 module Maximus
+  # @since 0.1.0
   class Brakeman < Maximus::Lint
 
     # Brakeman (requires Rails)
+    #
+    # @see Lint#initialize
     def result
 
       return unless @@is_rails
@@ -35,7 +38,10 @@ module Maximus
             end
           end
         end
-        brakeman = JSON.parse(brakeman.to_json) #don't event ask
+        # The output of brakeman is a mix of strings and symbols
+        #   but resetting the JSON like this standardizes everything.
+        # @todo Better way to get around this?
+        brakeman = JSON.parse(brakeman.to_json)
       end
 
       @output[:files_inspected] ||= files_inspected('rb', ' ')
@@ -45,7 +51,10 @@ module Maximus
 
     private
 
-    # Convert to maximus format
+    # Convert to {file:README.md Maximus format}
+    #
+    # @param error [Hash] lint error
+    # @return [Hash]
     def hash_for_brakeman(error, type)
       {
         linter: error['warning_type'],

data/lib/maximus/lints/jshint.rb

@@ -1,7 +1,10 @@
 module Maximus
+  # @since 0.1.0
   class Jshint < Maximus::Lint
 
     # JSHint (requires node module)
+    #
+    # @see Lint#initialize
     def result
       @task = 'jshint'
       @path ||= @@is_rails ? "#{@opts[:root_dir]}/app/assets" : "#{@opts[:root_dir]}source/assets"

data/lib/maximus/lints/railsbp.rb

@@ -1,7 +1,10 @@
 module Maximus
+  # @since 0.1.0
   class Railsbp < Maximus::Lint
 
     # rails_best_practice (requires Rails)
+    #
+    # @see Lint#initialize
     def result
 
       return unless @@is_rails
@@ -26,7 +29,10 @@ module Maximus
             railsbp[file.gsub(Rails.root.to_s, '')[1..-1].to_sym] = errors.map { |o| hash_for_railsbp(o) }
           end
         end
-        railsbp = JSON.parse(railsbp.to_json) #don't event ask
+        # The output of railsbp is a mix of strings and symbols
+        #   but resetting the JSON like this standardizes everything.
+        # @todo Better way to get around this?
+        railsbp = JSON.parse(railsbp.to_json)
       end
 
       @output[:files_inspected] ||= files_inspected('rb', ' ')
@@ -36,7 +42,10 @@ module Maximus
 
     private
 
-    # Convert to maximus format
+    # Convert to {file:README.md Maximus format}
+    #
+    # @param error [Hash] lint error
+    # @return [Hash]
     def hash_for_railsbp(error)
       {
         linter: error['message'].gsub(/\((.*)\)/, '').strip.parameterize('_').camelize,

data/lib/maximus/lints/rubocop.rb

@@ -1,7 +1,10 @@
 module Maximus
+  # @since 0.1.0
   class Rubocop < Maximus::Lint
 
     # RuboCop
+    #
+    # @see Lint#initialize
     def result
       @task = 'rubocop'
       @path ||= @@is_rails ? "#{@opts[:root_dir]}/app" : "#{@opts[:root_dir]}/*.rb"

data/lib/maximus/lints/scsslint.rb

@@ -1,7 +1,10 @@
 module Maximus
+  # @since 0.1.0
   class Scsslint < Maximus::Lint
 
     # SCSS-Lint
+    #
+    # @see Lint#initialize
     def result
       @task = 'scsslint'
       @path ||= @@is_rails ? "#{@opts[:root_dir]}/app/assets/stylesheets" : "#{@opts[:root_dir]}/source/assets/stylesheets"

data/lib/maximus/reporter/git-lines.sh

@@ -1,7 +1,7 @@
 #!/bin/bash
 
 # http://stackoverflow.com/questions/8259851/using-git-diff-how-can-i-get-added-and-modified-lines-numbers
-# TODO - this function is tricky because I don't fully understand regex in BASH. Also, getting line hunks from git is tricky. This will likely need to be refactored
+# @todo this function is tricky because I don't fully understand regex in BASH. Also, getting line hunks from git is tricky. This will likely need to be refactored
 function lines-added(){
   local path=
   local line=

data/lib/maximus/statistic.rb

@@ -1,20 +1,28 @@
-
 module Maximus
+  # @since 0.1.0
   class Statistic
     attr_accessor :output
 
     include Helper
 
-    # opts - Lint options (default: {})
-    #    :is_dev - wether or not this is being called by a rake task
-    #    :root_dir - absolute path to working directory (optional)
-    #    :port - 4-digit port number (optional)
-    #    :base_url - standard domain with http:// (default: http://localhost:3000) (optional)
-    #    :path - default set in methods (optional)
-    # All statistics should have the following:
-    # def result method to handle the actual parsing
-    # TODO - should this be def output to be more consistent?
-    # Didn't want to trip over the instance variable @output
+    # Gather info about how the code performs
+    #
+    # All defined statistics require a "result" method
+    # @example the result method in the child class
+    #   def result(opts = {})
+    #     @path ||= 'path/or/**/glob/to/files''
+    #     stat_data = JSON.parse(`some-command-line-stat-runner`)
+    #     @output
+    #  end
+    #
+    # @param opts [Hash] the options to create a lint with.
+    # @option opts [Boolean] :is_dev (false) whether or not the class was initialized from the command line
+    # @option opts [String] :root_dir base directory
+    # @option opts [String] :base_url ('http://localhost:3000/') the host
+    # @option opts [String, Integer] :port port number
+    # @option opts [String, Array] :path ('') path to files. Accepts glob notation
+    #
+    # @return output [Hash] combined and refined data from statistic
     def initialize(opts = {})
       opts[:is_dev] ||= false
       opts[:root_dir] ||= root_dir
@@ -38,6 +46,7 @@ module Maximus
     protected
 
     # Organize stat output on the @output variable
+    #
     # Adds @output[:statistics][:filepath] with all statistic data
     def refine_stats(stats_cli, file_path)
 
@@ -50,10 +59,10 @@ module Maximus
       stats = JSON.parse(stats_cli)
       @output[:statistics][file_path.to_sym] ||= {}
 
-      # TODO - is there a better way to do this?
+      # @todo is there a better way to do this?
       fp = @output[:statistics][file_path.to_s.to_sym]
 
-      # TODO - Can I do like a self << thing here?
+      # @todo Can I do like a self << thing here?
       stats.each do |stat, value|
         fp[stat.to_sym] = value
       end

data/lib/maximus/statistics/phantomas.rb

@@ -1,8 +1,10 @@
 module Maximus
+  # @since 0.1.0
   class Phantomas < Maximus::Statistic
 
-    # path can be array or string of URLS. Include http://
-    # By default, checks homepage
+    # Phantomas evaluates page performance with phantomjs and node
+    #
+    # @see Statistic#initialize
     def result
 
       node_module_exists('phantomjs', 'brew install')
@@ -22,6 +24,7 @@ module Maximus
 
     # Organize stat output on the @output variable
     # Adds @output[:statistics][:filepath] with all statistic data
+    # @return [void] goes to refine statistics
     def phantomas_by_url(url, phantomas_cli)
       puts "Phantomas on #{@opts[:base_url] + url}".color(:green)
       phantomas = `#{phantomas_cli} #{@opts[:base_url] + url}`

data/lib/maximus/statistics/stylestats.rb

@@ -1,8 +1,14 @@
 module Maximus
+  # @since 0.1.0
   class Stylestats < Maximus::Statistic
 
     # @path array preferrably absolute paths, but relative should work
-    # If stylestatting one file, pass that as an array, i.e. ['/absolute/to/public/assets/application.css']
+    # If stylestatting one file, pass that as an array
+    #
+    # @example stylestat one file
+    #   Maximus::Stylestats.new({path: ['/absolute/to/public/assets/application.css']}).result
+    #
+    # @see Statistic#initialize
     def result
 
       node_module_exists('stylestats')
@@ -27,10 +33,10 @@ module Maximus
       end
 
       if @@is_rails
-        # TODO - I'd rather Rake::Task but it's not working in different directories
+        # @todo I'd rather Rake::Task but it's not working in different directories
         Dir.chdir(@opts[:root_dir]) do
           if @@is_dev
-            # TODO - review that this may not be best practice, but it's really noisy in the console
+            # @todo review that this may not be best practice, but it's really noisy in the console
             quietly { `rake assets:clobber` }
           else
             `rake assets:clobber`
@@ -45,11 +51,11 @@ module Maximus
 
     private
 
-    # Find all CSS files
-    # Will compile using sprockets if Rails
-    # Will compile using built-in Sass engine otherwise
-    # Compass friendly
-    # Returns Array of CSS files
+    # Find all CSS files or compile.
+    # Uses sprockets if Rails; Sass engine otherwise.
+    # Compass is supported
+    #
+    # @return [Array] CSS files
     def find_css_files
       searched_files = []
 
@@ -60,10 +66,10 @@ module Maximus
         puts "\n"
         puts 'Compiling assets for stylestats...'.color(:blue)
 
-        # TODO - I'd rather Rake::Task but it's not working in different directories
+        # @todo I'd rather Rake::Task but it's not working in different directories
         Dir.chdir(@opts[:root_dir]) do
           if @@is_dev
-             # TODO - review that this may not be best practice, but it's really noisy in the console
+             # @todo review that this may not be best practice, but it's really noisy in the console
             quietly { `rake assets:precompile` }
           else
             `rake assets:precompile`
@@ -93,7 +99,7 @@ module Maximus
         @path += ".scss"
 
         Dir[@path].select { |f| File.file? f }.each do |file|
-          # TODO - don't compile file if it starts with an underscore
+          # @todo don't compile file if it starts with an underscore
           scss_file = File.open(file, 'rb') { |f| f.read }
 
           output_file = File.open( file.split('.').reverse.drop(1).reverse.join('.'), "w" )

data/lib/maximus/statistics/wraith.rb

@@ -1,11 +1,12 @@
 module Maximus
+  # @since 0.1.0
   class Wraith < Maximus::Statistic
 
     # By default checks homepage
     # Requires config to be in config/wraith/history.yaml
     # Adds a new config/wraith/history.yaml if not present
     # Path should be an Array defined as [{ label: url }]
-    # Returns Hash as defined in the wraith_parse method
+    # @see Statistic#initialize
     def result
 
       node_module_exists('phantomjs', 'brew install')
@@ -29,7 +30,7 @@ module Maximus
         wraith_yaml_reset
 
         # If the paths have been updated, call a timeout and run history again
-        # TODO - this doesn't work very well. It puts the new shots in the history folder,
+        # @todo this doesn't work very well. It puts the new shots in the history folder,
         # even with absolute paths. Could be a bug in wraith
         YAML.load_file(@wraith_config_file)['paths'].each do |label, url|
           edit_yaml(@wraith_config_file) do |file|
@@ -53,7 +54,7 @@ module Maximus
     # Get a diff percentage of all changes by label and screensize
     # { path: { percent_changed: [{ size: percent_diff }] } }
     # Example {:statistics=>{:/=>{:percent_changed=>[{1024=>0.0}, {767=>0.0}, {1024=>0.0}, {767=>0.0}, {1024=>0.0}, {767=>0.0}, {1024=>0.0}, {767=>0.0}] } }}
-    # Returns Hash
+    # @return [Hash]
     def wraith_parse(wraith_config_file = @wraith_config_file)
       paths = YAML.load_file(wraith_config_file)['paths']
       Dir.glob("#{@opts[:root_dir]}/maximus_wraith/**/*.txt").select { |f| File.file? f }.each do |file|
@@ -69,7 +70,10 @@ module Maximus
       @output
     end
 
-    # Update the root domain (docker ports and addresses may change) and set paths as defined in @path
+    # Update the root domain (docker ports and addresses may change)
+    # and set paths as defined in @path
+    #
+    # @return [void] but updates instance variables
     def wraith_yaml_reset(wraith_config_file = @wraith_config_file)
       edit_yaml(wraith_config_file) do |file|
         unless @@is_dev