jslint_on_rails 1.0.0

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2009 Jakub Suder
+
+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/README.markdown

@@ -0,0 +1,167 @@
+# JSLint on Rails
+
+**JSLint on Rails** is a Ruby gem and Rails plugin which lets you run
+the [JSLint JavaScript code checker](http://jslint.com) on your Javascript code easily.
+
+It can be installed either as a Rails plugin (the recommended method for Rails), or as a gem (for other frameworks).
+
+Note: to run JSLint on Rails, you need to have **Java** available on your machine - it's required because JSLint is
+itself written in JavaScript, and is run using the [Rhino](http://www.mozilla.org/rhino) JavaScript engine (written in
+Java). Any decent version of Java will do (and by decent I mean 5.0 or later).
+
+
+## Installation (Rails)
+
+If you use Rails, you can install the library as a plugin - it's less work to set it up this way.
+To install the plugin, use this command:
+
+    ./script/plugin install git://github.com/psionides/jslint_on_rails.git
+
+This will create for you a sample `jslint.yml` config file in your config directory.
+
+
+## Installation (other frameworks)
+
+If you use Merb or some other framework, you need to install JSLint as a Ruby gem (you can do that in Rails too - the
+advantage of this method is that it may be easier to update to newer versions later).
+
+To use JSLint as a gem, follow these steps:
+
+* install the gem in your application using whatever technique is recommended for your framework (e.g. using gem
+bundler, or just plain old `gem install jslint_on_rails`)
+* in your Rakefile, add a line to load the JSLint tasks:
+
+        require 'jslint/tasks'
+
+* below that line, set JSLint's config_path variable to point it to a place where you want your JSLint configuration
+file to be kept - for example:
+
+        JSLint.config_path = "config/jslint.yml"
+    
+* run a rake task which will generate a sample config file for you:
+
+        rake jslint:copy_config
+
+
+## Installation (custom)
+
+If you wish to write your own rake task to run JSLint, you can create and execute the JSLint object manually:
+
+    require 'jslint'
+    lint = JSLint::Lint.new(
+      :paths => ['public/javascripts/**/*.js'],
+      :exclude_paths => ['public/javascripts/vendor/**/*.js'],
+      :config_path => 'config/jslint.yml'
+    )
+    lint.run
+
+
+## Configuration
+
+Whatever method you use for installation, a YAML config file should be created for you. In this file, you can:
+
+* define which Javascript files are checked by default; you'll almost certainly want to change that, because the default
+is `public/javascripts/**/*.js` which means all Javascript files, and you probably don't want JSLint to check entire
+jQuery, Prototype or whatever other libraries you use - so change this so that only your scripts are checked (you can
+put multiple entries under "paths:" and "exclude_paths:")
+* tweak JSLint options to enable or disable specific checks - I've set the defaults to what I believe is reasonable,
+but what's reasonable for me may not be reasonable for you
+
+
+## Running
+
+To start the check, run the rake task:
+
+    rake jslint
+
+You will get a result like this (if everything goes well):
+
+    Running JSLint:
+    
+    checking public/javascripts/Event.js... OK
+    checking public/javascripts/Map.js... OK
+    checking public/javascripts/Marker.js... OK
+    checking public/javascripts/Reports.js... OK
+    
+    No JS errors found.
+
+If anything is wrong, you will get something like this instead:
+
+    Running JSLint:
+    
+    checking public/javascripts/Event.js... 2 errors:
+    
+    Lint at line 24 character 15: Use '===' to compare with 'null'.
+    if (a == null && b == null) {
+    
+    Lint at line 72 character 6: Extra comma.
+    },
+    
+    checking public/javascripts/Marker.js... 1 error:
+    
+    Lint at line 275 character 27: Missing radix parameter.
+    var x = parseInt(mapX);
+    
+    
+    Found 3 errors.
+    rake aborted!
+    JSLint test failed.
+
+If you want to test specific file or files (just once, without modifying the config), you can pass paths to include
+and/or paths to exclude to the rake task:
+
+    rake jslint paths=public/javascripts/models/*.js,public/javascripts/lib/*.js exclude_paths=public/javascripts/lib/jquery.js
+
+For the best effect, you should include JSLint check in your Continuous Integration build - that way, you'll get
+immediate notification when you've committed JS code with errors.
+
+
+## Additional options
+
+I've added some additional options to JSLint to get rid of some warnings which I thought didn't make sense. They're all
+disabled by default, but feel free to enable any or all of them if you feel abused by JSLint.
+
+Here's a documentation for all the extra options:
+
+
+### lastsemic
+
+If set to true, this will ignore warnings about missing semicolon after a statement, if the statement is the last one in
+a block or function. I've added this because I like to omit the semicolon in one-liner anonymous functions, in
+situations like this:
+
+    var ids = $$('.entry').map(function(e) { return e.id });
+
+
+### newstat
+
+Allows you to use a call to 'new' as a whole statement, without assigning the result anywhere. Sometimes you want to
+create an instance of a class, but you don't need to assign it anywhere - the call to constructor starts the action
+automatically. This includes calls like `new Ajax.Request(...)` or `new Effect.Highlight(...)` used when working with
+Prototype and Scriptaculous.
+
+
+### statinexp
+
+JSLint has a warning that says "Expected an assignment or function call and instead saw an expression" - you get it
+when you write an expression and you don't use it for anything, like if you wrote such line:
+
+    $$('.entry').length;
+
+Just checking the length without assigning it anywhere or passing to any function doesn't make any sense, so it's good
+that JSLint complains. However, there are some cases where the code makes perfect sense, but JSLint still thinks it
+doesn't. Examples:
+
+    element && element.show();  // call show only if element is not null
+    selected ? element.show() : element.hide();  // more readable than if & else with brackets
+
+So I've tweaked the code that creates this warning so that it doesn't print it if the code makes sense. Specifically:
+
+* expressions joined with && or || are accepted if the last one in the line is a statement
+* expressions with ?: are accepted if both alternatives (before and after the colon) are statements
+
+
+## Credits
+
+* JSLint on Rails was created by [Jakub Suder](http://psionides.jogger.pl), licensed under MIT License
+* JSLint was created by [Douglas Crockford](http://jslint.com)

data/config/jslint.yml

@@ -0,0 +1,79 @@
+# ------------ rake task options ------------
+
+# JS files to check by default, if no parameters are passed to rake jslint
+# (you may want to limit this only to your own scripts and exclude any external scripts and frameworks)
+
+# this can be overridden by adding 'paths' and 'exclude_paths' parameter to rake command:
+#   rake jslint paths=path1,path2,... exclude_paths=library1,library2,...
+
+paths:
+  - public/javascripts/**/*.js
+
+exclude_paths:
+
+
+# ------------ jslint options ------------
+# see http://www.jslint.com/lint.html#options for more detailed explanations
+
+# "enforce" type options (true means potentially more warnings)
+
+adsafe:   false     # true if ADsafe rules should be enforced. See http://www.ADsafe.org/
+bitwise:  true      # true if bitwise operators should not be allowed
+newcap:   true      # true if Initial Caps must be used with constructor functions
+eqeqeq:   false     # true if === should be required (for ALL equality comparisons)
+immed:    false     # true if immediate function invocations must be wrapped in parens
+nomen:    false     # true if initial or trailing underscore in identifiers should be forbidden
+onevar:   false     # true if only one var statement per function should be allowed
+plusplus: false     # true if ++ and -- should not be allowed
+regexp:   false     # true if . and [^...] should not be allowed in RegExp literals
+safe:     false     # true if the safe subset rules are enforced (used by ADsafe)
+strict:   false     # true if the ES5 "use strict"; pragma is required
+undef:    false     # true if variables must be declared before used
+white:    false     # true if strict whitespace rules apply (see also 'indent' option)
+
+# "allow" type options (false means potentially more warnings)
+
+cap:      false     # true if upper case HTML should be allowed
+css:      true      # true if CSS workarounds should be tolerated
+debug:    false     # true if debugger statements should be allowed (set to false before going into production)
+evil:     false     # true if eval should be allowed
+forin:    true      # true if unfiltered 'for in' statements should be allowed
+fragment: true      # true if HTML fragments should be allowed
+laxbreak: false     # true if statement breaks should not be checked
+on:       false     # true if HTML event handlers (e.g. onclick="...") should be allowed
+sub:      false     # true if subscript notation may be used for expressions better expressed in dot notation
+
+# other options
+
+maxlen:   120       # Maximum line length
+indent:   2         # Number of spaces that should be used for indentation - used only if 'white' option is set
+maxerr:   50        # The maximum number of warnings reported (per file)
+passfail: false     # true if the scan should stop on first error (per file)
+# following are relevant only if undef = true
+predef:   ''        # Names of predefined global variables - comma-separated string
+browser:  true      # true if the standard browser globals should be predefined
+rhino:    false     # true if the Rhino environment globals should be predefined
+sidebar:  false     # true if the Windows Sidebar Gadgets globals should be predefined
+widget:   false     # true if the Yahoo Widgets globals should be predefined
+devel:    true      # true if functions like alert, confirm, console, prompt etc. are predefined
+
+
+# ------------ jslint_on_rails custom lint options (switch to true to disable some annoying warnings) ------------
+
+# ignores "missing semicolon" warning at the end of a function; this lets you write one-liners
+# like: x.map(function(i) { return i + 1 }); without having to put a second semicolon inside the function
+lastsemic: false
+
+# allows you to use the 'new' expression as a statement (without assignment)
+# so you can call e.g. new Ajax.Request(...), new Effect.Highlight(...) without assigning to a dummy variable
+newstat: false
+
+# ignores the "Expected an assignment or function call and instead saw an expression" warning,
+# if the expression contains a proper statement and makes sense; this lets you write things like:
+#    element && element.show();
+#    valid || other || lastChance || alert('OMG!');
+#    selected ? show() : hide();
+# although these will still cause a warning:
+#    element && link;
+#    selected ? 5 : 10;
+statinexp: false

data/lib/jslint.rb

@@ -0,0 +1,3 @@
+require File.expand_path(File.dirname(__FILE__) + '/jslint/errors')
+require File.expand_path(File.dirname(__FILE__) + '/jslint/utils')
+require File.expand_path(File.dirname(__FILE__) + '/jslint/lint')

data/lib/jslint/errors.rb

@@ -0,0 +1,9 @@
+module JSLint
+
+  class NoJavaException < StandardError
+  end
+
+  class LintCheckFailure < StandardError
+  end
+
+end

data/lib/jslint/lint.rb

@@ -0,0 +1,64 @@
+module JSLint
+
+  PATH = File.dirname(__FILE__)
+
+  TEST_JAR_FILE = File.expand_path("#{PATH}/../../vendor/test.jar")
+  RHINO_JAR_FILE = File.expand_path("#{PATH}/../../vendor/rhino.jar")
+  TEST_JAR_CLASS = "Test"
+  RHINO_JAR_CLASS = "org.mozilla.javascript.tools.shell.Main"
+
+  JSLINT_FILE = File.expand_path("#{PATH}/../../vendor/jslint.js")
+
+  class Lint
+
+    # available options:
+    # :paths => [list of paths...]
+    # :exclude_paths => [list of exluded paths...]
+    # :config_path => path to custom config file (can be set via JSLint.config_path too)
+    def initialize(options = {})
+      default_config = Utils.load_config_file(DEFAULT_CONFIG_FILE)
+      custom_config = Utils.load_config_file(options[:config_path] || JSLint.config_path)
+      @config = default_config.merge(custom_config)
+
+      included_files = files_matching_paths(options, :paths)
+      excluded_files = files_matching_paths(options, :exclude_paths)
+      @file_list = Utils.exclude_files(included_files, excluded_files)
+
+      ['paths', 'exclude_paths', 'config_path'].each { |field| @config.delete(field) }
+    end
+
+    def run
+      check_java
+      puts "Running JSLint:\n\n"
+      command = "java -cp #{RHINO_JAR_FILE} #{RHINO_JAR_CLASS} #{JSLINT_FILE} #{option_string} #{@file_list.join(' ')}"
+      success = system(command)
+      raise LintCheckFailure, "JSLint test failed." unless success
+    end
+
+
+    private
+
+    def option_string
+      @config.map { |k, v| "#{k}=#{v.inspect}" }.join(',')
+    end
+
+    def check_java
+      unless @java_ok
+        java_test = %x(java -cp #{TEST_JAR_FILE} #{TEST_JAR_CLASS})
+        if java_test.strip == "OK"
+          @java_ok = true
+        else
+          raise NoJavaException, "Please install Java before running JSLint."
+        end
+      end
+    end
+
+    def files_matching_paths(options, field)
+      path_list = options[field] || @config[field.to_s] || []
+      file_list = path_list.map { |p| Dir[p] }.flatten
+      Utils.unique_files(file_list)
+    end
+
+  end
+
+end

data/lib/jslint/rails.rb

@@ -0,0 +1,2 @@
+# for Rails, set config file path to config/jslint.yml in Rails root
+JSLint.config_path = File.expand_path(RAILS_ROOT + '/config/jslint.yml')

data/lib/jslint/tasks.rb

@@ -0,0 +1,26 @@
+require File.expand_path(File.dirname(__FILE__) + '/../jslint')
+
+desc "Run JSLint check on selected Javascript files"
+task :jslint do
+  include_paths = JSLint::Utils.paths_from_command_line('paths')
+  exclude_paths = JSLint::Utils.paths_from_command_line('exclude_paths')
+
+  if include_paths && exclude_paths.nil?
+    # if you pass paths= on command line but not exclude_paths=, and you have exclude_paths
+    # set in the config file, then the old exclude pattern will be used against the new
+    # include pattern, which may be very confusing...
+    exclude_paths = []
+  end
+
+  lint = JSLint::Lint.new :paths => include_paths, :exclude_paths => exclude_paths
+  lint.run
+end
+
+namespace :jslint do
+
+  desc "Create a copy of the default JSLint config file in your config directory"
+  task :copy_config do
+    JSLint::Utils.copy_config_file
+  end
+
+end

data/lib/jslint/utils.rb

@@ -0,0 +1,70 @@
+require 'ftools'
+
+module JSLint
+
+  DEFAULT_CONFIG_FILE = File.expand_path(File.dirname(__FILE__) + "/../../config/jslint.yml")
+
+  class << self
+    attr_accessor :config_path
+  end
+
+  module Utils
+    class << self
+
+      def load_config_file(file_name)
+        if file_name && File.exists?(file_name) && File.file?(file_name) && File.readable?(file_name)
+          YAML.load_file(file_name)
+        else
+          {}
+        end
+      end
+
+      # workaround for a problem with case-insensitive file systems like HFS on Mac
+      def unique_files(list)
+        files = []
+        list.each do |entry|
+          files << entry unless files.any? { |f| File.identical?(f, entry) }
+        end
+        files
+      end
+
+      # workaround for a problem with case-insensitive file systems like HFS on Mac
+      def exclude_files(list, excluded)
+        list.reject { |entry| excluded.any? { |f| File.identical?(f, entry) }}
+      end
+
+      def paths_from_command_line(field)
+        argument = ENV[field] || ENV[field.upcase]
+        argument && argument.split(/,/)
+      end
+
+      def copy_config_file
+        raise ArgumentError, "Please set JSLint.config_path" if JSLint.config_path.nil?
+        print "Copying default config file to #{File.expand_path(JSLint.config_path)}... "
+        if File.exists?(JSLint.config_path)
+          puts "\n\nWarning: config file exists, so it won't be overwritten. " +
+               "You can copy it manually from the jslint_on_rails directory if you want to reset it."
+        else
+          File.copy(JSLint::DEFAULT_CONFIG_FILE, JSLint.config_path)
+          puts "OK."
+        end
+      end
+
+      def remove_config_file
+        raise ArgumentError, "Please set JSLint.config_path" if JSLint.config_path.nil?
+        print "Removing config file... "
+        if File.exists?(JSLint.config_path) && File.file?(JSLint.config_path)
+          if File.read(JSLint.config_path) == File.read(JSLint::DEFAULT_CONFIG_FILE)
+            File.delete(JSLint.config_path)
+            puts "OK."
+          else
+            puts "File was modified, so it won't be deleted automatically."
+          end
+        else
+          puts "OK (no config file found)."
+        end
+      end
+
+    end
+  end
+end