CoffeeLint

Run

Overview

CoffeeLint is a style checker that helps keep CoffeeScript code clean and consistent. CoffeeScript does a great job at insulating programmers from many of JavaScript's bad parts, but it won't help enforce a consistent style across a code base. CoffeeLint can help with that.

If you have an idea, a bug report or anything else to say, reach out on the issues page.

Installation

To install, make sure you have a working version of the latest stable version of Node and NPM (the Node Package Manager) and then run:

npm install -g coffeelint

Leave off the g if you do not want to install globally.

Usage

Once you have Coffeelint installed, to lint your scripts, run:

coffeelint application.coffee

To specify your own configuration file, do the following:

coffeelint -f coffeelint.json application.coffee

If any errors were found, a non-zero code will be returned.

To generate a configuration file, do

coffeelint --makeconfig > coffeelint.json

You can then configure the rules to your liking.

New in 1.0: CoffeeLint will automatically pick up config files. When linting a file (as opposed to stdin) it will walk up the directory tree looking for a coffeelint.json or a package.json that has a "coffeelintConfig" object. If neither of those are found or you're linting from stdin it will check your home for a coffeelint.json file.

Options

By default, CoffeeLint will help ensure you are writing idiomatic CoffeeScript, but every rule is optional and configurable so it can be tuned to fit your preferred coding style. To override any of CoffeeLint's default options, generate a configuration file and tweak it as needed. To enable an option, set its level to error, and to disable an option, set its level to ignore. If you set the level to warn, violations will be reported, but won't cause a non-zero exit code.

Here's a rundown of CoffeeLint's rules:

Name Description
arrow_spacing

This rule checks to see that there is spacing before and after the arrow operator that declares a function. This rule is disabled by default.

Note that if arrow_spacing is enabled, and you pass an empty function as a parameter, arrow_spacing will accept either a space or no space in-between the arrow operator and the parenthesis

# Both of this will not trigger an error,
# even with arrow_spacing enabled.
x(-> 3)
x( -> 3)

# However, this will trigger an error
x((a,b)-> 3)

default level: ignore

camel_case_classes This rule mandates that all class names are CamelCased. Camel casing class names is a generally accepted way of distinguishing constructor functions - which require the 'new' prefix to behave properly - from plain old functions.
# Good!
class BoaConstrictor

# Bad!
class boaConstrictor

This rule is enabled by default.

default level: error

coffeescript_error [no description provided]

default level: error

colon_assignment_spacing

This rule checks to see that there is spacing before and after the colon in a colon assignment (i.e., classes, objects). The spacing amount is specified by spacing.left and spacing.right, respectively. A zero value means no spacing required.


#
# If spacing.left and spacing.right is 1
#

# Good
object = {spacing : true}
class Dog
  canBark : true

# Bad
object = {spacing: true}
class Cat
  canBark: false

default level: ignore

cyclomatic_complexity Examine the complexity of your application.

default level: ignore

duplicate_key Prevents defining duplicate keys in object literals and classes

default level: error

empty_constructor_needs_parens Requires constructors with no parameters to include the parens

default level: ignore

indentation This rule imposes a standard number of spaces to be used for indentation. Since whitespace is significant in CoffeeScript, it's critical that a project chooses a standard indentation format and stays consistent. Other roads lead to darkness.
 #
Enabling this option will prevent this ugly
# but otherwise valid CoffeeScript.
twoSpaces = () ->
  fourSpaces = () ->
      eightSpaces = () ->
            'this is valid CoffeeScript'


Two space indentation is enabled by default.

default level: error

line_endings This rule ensures your project uses only windows or unix line endings. This rule is disabled by default.

default level: ignore

max_line_length This rule imposes a maximum line length on your code. Python's style guide does a good job explaining why you might want to limit the length of your lines, though this is a matter of taste. Lines can be no longer than eighty characters by default.

default level: error

missing_fat_arrows Warns when you use `this` inside a function that wasn't defined with a fat arrow. This rule does not apply to methods defined in a class, since they have `this` bound to the class instance (or the class itself, for class methods). It is impossible to statically determine whether a function using `this` will be bound with the correct `this` value due to language features like `Function.prototype.call` and `Function.prototype.bind`, so this rule may produce false positives.

default level: ignore

newlines_after_classes Checks the number of newlines between classes and other code

default level: ignore

no_backticks Backticks allow snippets of JavaScript to be embedded in CoffeeScript. While some folks consider backticks useful in a few niche circumstances, they should be avoided because so none of JavaScript's "bad parts", like with and eval, sneak into CoffeeScript. This rule is enabled by default.

default level: error

no_debugger This rule detects the `debugger` statement. This rule is `warn` by default.

default level: warn

no_empty_functions Disallows declaring empty functions. The goal of this rule is that unintentional empty callbacks can be detected:
someFunctionWithCallback ->
doSomethingSignificant()

The problem is that the call to doSomethingSignificant will be made regardless of someFunctionWithCallback's execution. It can be because you did not indent the call to doSomethingSignificant properly. If you really meant that someFunctionWithCallback should call a callback that does nothing, you can write your code this way:
someFunctionWithCallback ->
    undefined
doSomethingSignificant()

default level: ignore

no_empty_param_list This rule prohibits empty parameter lists in function definitions.
# The empty parameter list in here is unnecessary:
myFunction = () ->

# We might favor this instead:
myFunction = ->

Empty parameter lists are permitted by default.

default level: ignore

no_implicit_braces This rule prohibits implicit braces when declaring object literals. Implicit braces can make code more difficult to understand, especially when used in combination with optional parenthesis.
# Do you find this code ambiguous? Is it a
# function call with three arguments or four?
myFunction a, b, 1:2, 3:4

# While the same code written in a more
# explicit manner has no ambiguity.
myFunction(a, b, {1:2, 3:4})

Implicit braces are permitted by default, since their use is idiomatic CoffeeScript.

default level: ignore

no_implicit_parens This rule prohibits implicit parens on function calls.
# Some folks don't like this style of coding.
myFunction a, b, c

# And would rather it always be written like this:
myFunction(a, b, c)

Implicit parens are permitted by default, since their use is idiomatic CoffeeScript.

default level: ignore

no_interpolation_in_single_quotes This rule prohibits string interpolation in a single quoted string.
# String interpolation in single quotes is not allowed:
foo = '#{bar}'

# Double quotes is OK of course
foo = "#{bar}"

String interpolation in single quoted strings is permitted by default.

default level: ignore

no_plusplus This rule forbids the increment and decrement arithmetic operators. Some people believe the ++ and -- to be cryptic and the cause of bugs due to misunderstandings of their precedence rules. This rule is disabled by default.

default level: ignore

no_stand_alone_at This rule checks that no stand alone @ are in use, they are discouraged. Further information in CoffeScript issue #1601

default level: ignore

no_tabs This rule forbids tabs in indentation. Enough said. It is enabled by default.

default level: error

no_throwing_strings This rule forbids throwing string literals or interpolations. While JavaScript (and CoffeeScript by extension) allow any expression to be thrown, it is best to only throw Error objects, because they contain valuable debugging information like the stack trace. Because of JavaScript's dynamic nature, CoffeeLint cannot ensure you are always throwing instances of Error. It will only catch the simple but real case of throwing literal strings.
# CoffeeLint will catch this:
throw "i made a boo boo"

# ... but not this:
throw getSomeString()

This rule is enabled by default.

default level: error

no_trailing_semicolons This rule prohibits trailing semicolons, since they are needless cruft in CoffeeScript.
# This semicolon is meaningful.
x = '1234'; console.log(x)

# This semicolon is redundant.
alert('end of line');

Trailing semicolons are forbidden by default.

default level: error

no_trailing_whitespace This rule forbids trailing whitespace in your code, since it is needless cruft. It is enabled by default.

default level: error

no_unnecessary_double_quotes This rule prohibits double quotes unless string interpolation is used or the string contains single quotes.
# Double quotes are discouraged:
foo = "bar"

# Unless string interpolation is used:
foo = "#{bar}baz"

# Or they prevent cumbersome escaping:
foo = "I'm just following the 'rules'"

Double quotes are permitted by default.

default level: ignore

no_unnecessary_fat_arrows Disallows defining functions with fat arrows when `this` is not used within the function.

default level: warn

non_empty_constructor_needs_parens Requires constructors with parameters to include the parens

default level: ignore

space_operators This rule enforces that operators have space around them.

default level: ignore

API

If you'd like to run CoffeeScript in the browser or any other Javascript runtime, include coffee-script.js and coffeelint.js and you're off to the races. Then you can call CoffeeLint directly with the following API:

coffeelint.lint(source, configuration)

Lints the CoffeeScript source with the given configuration and returns an array of lint errors and warnings. If the array is empty, all is well. Compile time errors will be thrown. An error is a Javascript object with the following properties:

{
    rule :      'Name of the violated rule',
    lineNumber: 'Number of the line that caused the violation',
    level:      'The severity level of the violated rule',
    message:    'Information about the violated rule',
    context:    'Optional details about why the rule was violated'
}

coffeelint.registerRule(RuleConstructor)

Registers a custom rule that may be run by CoffeeLint. If the rule is ignored by default it will still require overriding it's level just like the default rules. They have actually all be re-implemented as pluggable rules that come bundled in CoffeeLint.

Loading Custom Rules

Not every possible rule will be included in the CoffeeLint project. Maybe it's very specific to your project, or it's not specific to CoffeeScript.

By convention rule authors add the keyword coffeelintrule to their npm package.json so custom rules can be found easily. Click here to list all currently available custom rules on npm.

For example, maybe you want to get a warning if you don't have a newline at the end of your files. We'll imagine you globally installed the package "coffeelint-newline-eof".

{
    // This name MUST match the default configuration of the rule being loaded.
    "newline_at_eof": {
        // NodeJS module to load. It can also be a path to the rule (useful for devleopment)
        "module": "coffeelint-newline-at-eof",
        // Maybe the rule author set it to error by default and you only want a warning.
        "level": "warn"
    }
}

Now every time you run CoffeeLint it will load that rule and override it's default level to "warn".

Building Custom Rules

CoffeeLint has three types of linters that run. In no particular order they are.

Rules may be loaded using

--rules /path/to/rules/
or
coffeelint.registerRule(RuleConstructor)
when outside of the CLI.

Rules do not have to be written in CoffeeScript. A new instance of each rule is constructed for each file, so the RuleConstructor must be a constructor function that generates a new clean instance of your rule when the new operator is used.

Your rule instance must have a .rule attribute with it's default configuration. "name", "level" "message", and "description" are all required. "level" must be one of 'ignore', 'warn', or 'error'. Once you have a valid rule configuration CoffeeLint requires you to implement one function depending on which type of linter your rule needs. lintLine(line, lineApi)
lintToken(token, tokenApi)
lintNode(node, astApi)
The second parameter of each is an object with helper functions. It's best to just check the source or look at how other plugins are using those.

If your function returns true it will generate an error. If you need override how the error is generated, maybe providing a context attribute, you can return an object that will get mixed into the generated error. The NoPlusPlus is a simple example of this.

The core rules have been rewritten as stand alone rules both to prove the system and provide examples of how to write rules. To get started no_plus_plus is a Token rule, no_tabs is a Line rule, and cyclomatic_complexity is an AST rule.

The

--rules
option will load every .js or .coffee file it finds and assume they export the RuleConstructor. Since the browser doesn't have a standard export system it's up to you to determine how you'll load your plugin and register it with
coffeelint.registerRule

Plugins

Some nice folks have coded up some cool CoffeeLint plugins for editors and build systems. Check them out:

About

CoffeeLint is open sourced under the MIT License. If you want to hack on the code, report a bug or suggest a new feature, head on over here.

Thanks to CoffeeScript's developers for a great language (and a re-usable Lexer). Thanks to the creators of JSLint, JSHint, Pylint, lint and my mother for inspiration.

Change Log

1.2.0-1.3.0

- 2014.04.17
  • New rule no_empty_functions
  • Improved documentation on how to contribute in README.md
  • Rules using the AST work with a minified version of CoffeeScript
  • Fixed line length check to account for windows line endings

1.1.0-1.2.0

- 2014.03.07
  • New rule no_debugger
  • New rule no_interpolation_in_single_quotes
  • New rule no_unnecessary_double_quotes
  • Strict mode for no_implicit_parens. Turning it off allows implicit parens when they span multiple lines.

1.0.8-1.1.0

- 2014.02.22
  • CoffeeScript 1.7 support
  • Dropped support for CoffeeScript 1.6. (Use ~1.0.0 if you still need it)

0.6.0-1.0.0

- 2013.11.21
  • CoffeeLint will detect config files by default.
  • New rule colon_assignment_spacing
  • New rule no_unnecessary_fat_arrows
  • New rule missing_fat_arrows
  • Added an option to no_trailing_whitespace to forbid trailing space on empty lines
  • Added an option to no_implicit_braces to allow unambiguous implicit braces
  • Fixed --makeconfig
  • New option: --checkstyle
  • Fixed invalid XML produced by --jslint
  • Removed the need for the -r flag. It remains for backward compatibility but doesn't do anything now

0.5.7-0.6.0

- 2013.10.10
  • New internal structure to support custom rules.
  • Dropped support for NodeJS 0.6.

0.5.6-0.5.7

- 2013.08.10
  • CSVReporter now has a column for last line to account for cyclomatic complexity spanning the length of the function
  • Added support for literate CoffeeScript
  • Dropped support for CoffeeScript 1.4 and 1.5
  • Fixed non_empty_constructor_needs_parens for namespaced constructors
  • Simplified the build process to allow installing direct from the git repo
  • More fixes to indentation checking (continued https://github.com/clutchski/coffeelint/issues/107)
  • Fixed spacing error when returning negative numbers (https://github.com/clutchski/coffeelint/issues/129)
  • Fixed arrow spacing in callback parameters (https://github.com/clutchski/coffeelint/issues/131)
  • Added beginning and end line numbers for cyclomatic complexity (https://github.com/clutchski/coffeelint/pull/134)
  • Added header to CSVReporter
  • Fixes for space_operators(https://github.com/clutchski/coffeelint/issues/137)

0.5.5-0.5.6

- 2013.06.07
  • Added no_empty_param_list rule.
  • Added the --makeconfig option.
  • CoffeeScript 1.5 and 1.6 compatibility
  • Fixed indentation of chained functions. (https://github.com/clutchski/coffeelint/issues/107, fixed 1/2 of #4)
  • Fixed bug in no_stand_alone_at (https://github.com/jashkenas/coffee-script/issues/1601)
  • Added arrow_spacing rule (require spaces around arrows)
  • Added empty_constructor_needs_parens
  • Added non_empty_constructor_needs_parens
  • Added duplicate_key (http://jslinterrors.com/duplicate-key-a/)
  • Added no_trailing_whitespace.allowed_in_comments rule option (Allow trailing space in comments. Created to allow markdown)
  • Added newlines_after_classes rule
  • Line length exception. Lines containing only a link are ignored.

0.5.4

- 2012.11.06
  • Support for default configuration file using environment variable COFFEELINT_CONFIG.

0.5.3

- 2012.11.06
  • Added no_stand_alone_at rule.
  • Fixed correctly reporting line numbers of compilation errors after line 10.
  • Fixed incomplete results output.

0.5.2

- 2012.09.18

0.5.1

- 2012.09.15

0.5.0

- 2012.09.08

0.4.0

- 2012.04.06

0.3.0

- 2012.03.13

0.2.0

- 2012.01.26

0.1.0

- 2012.01.22
Fork me on GitHub