tritondatacenter / jsstyle

cstyle-based JavaScript style checker

jsstyle

Overview

jsstyle is a style checker for JavaScript coding style. This tool is derived from the cstyle tool used to check for the style used in the Solaris kernel, sometimes known as "Bill Joy Normal Form". This tool is a little bit configurable. However it strives to enforces a single coding style based on that cstyle. See "Configuration Options" below.

The original cstyle tool can be found here: https://github.com/illumos/illumos-gate/blob/master/usr/src/tools/scripts/cstyle.pl

The document describing C Style is available here: http://www.cis.upenn.edu/~lee/06cse480/data/cstyle.ms.pdf

Examples of conditions checked by this tool include:

• Strings must be quoted with single quotes.
• Blocks must be indented with tabs, not spaces.
• Continuation lines must be indented with 4 spaces.
• Keywords (for, if, function, etc.) must be followed with a space.
• One line cannot contain multiple keywords.
• Relational operators must be surrounded with spaces.
• There must be no spaces between tabs, nor tabs between spaces.
• Lines must not end with whitespace.
• Multi-line block comments must start and end with a blank line.
• Return expressions must be parenthesized.

Status

No new features planned. The biggest known issue is that jsstyle doesn't grok regexes, so you usually need to wrap these in JSSTYLED comments (see below).

Usage

jsstyle [OPTIONS] file1.js [file2.js ...]

Configuration Options

Configuration options may be specified in a file (one option per line) with the "-f PATH" switch, or on the command line with the "-o OPTION1,OPTION2" switch.

As stated about, jsstyle is opinionated and intends to stay that way. That said, this author was arm twisted under duress to allow the following configurability.

doxygen                 Allow doxygen-style block comments `/** /*!`.
splint                  Allow splint-style lint comments `/*@ ... @*/`.
                        This is legacy. Does anyone use this?
indent=<NUM|tab>        An integer number of spaces for indentation, or
                        'tab' for tab indentation (the default).
strict-indent           Boolean option, set to 1 to force indents of spaces
                        to be a multiple of indent parameter.
line-length             An integer number to specify the maximum length
                        of a line (default: 80)
literal-string-quote    'single' (the default) or 'double'. Specifies
                        the preferred quote character for literal strings.
unparenthesized-return  Boolean option, set to 0 to disable the
                        "unparenthesized return expression" check.
blank-after-start-comment
                        Boolean option, set to 0 to disable the
                        "missing blank after start comment" check. `// `
blank-after-open-comment
                        Boolean option, set to 0 to disable the
                        "missing blank after open comment" check. `/* */`
no-blank-for-anon-function
                        Boolean option, set to 1 to allow anonymous
                        functions without blank before paren. `function() { ... }`
continuation-at-front   Boolean option, set to 1 to force continations
                        to be at the beginning rather than end of line.
leading-right-paren-ok  Boolean option, set to 1 to allow ) to start a
                        line.

whitespace-after-left-paren-ok
                        Boolean option, allow whitespace after a (
                        character.

leading-comma-ok        Boolean option to allow lines to begin with commas
                        (preceded by whitespace).

uncuddled-else-ok       Boolean option to allow for an else block to begin
                        on a new line.

"JSSTYLED"-comments

When you want jsstyle to ignore a line, you can use this:

/* JSSTYLED */
ignore = this + line;

Or for a block:

/* BEGIN JSSTYLED */
var here
  , be
  , some = funky
  , style
/* END JSSTYLED */

License

CDDL

jsstyle's Issues

fix warning on perl 5.22

Perl 5.22 was released in June, and added a new deprecation warning for unescaped braces inside regular expressions. See http://perldoc.perl.org/perl5220delta.html for details.

When running jsstyle on this Perl, I get:

$ jsstyle lib/jsprim.js 
Unescaped left brace in regex is deprecated, passed through in regex; marked by <-- HERE in m/\S{ <-- HERE / at /Users/dap/work/jsstyle/jsstyle line 666.

Is there a way to recursively style-check an entire folder?

For example I have the following code organization and I want to test all js file.

- routes
  |- user
  | |- a.js
  | |- b.js
  |- files
    |- another.js

move repo under joyent org

Rewrite regular expressions that start with '^' or end with '$'

jsstyle will warn on contents inside regular expressions. For example, a regular expression that contains double quotes will result in:

% make check
...
jsstyle  test/tst.env.js
test/tst.env.js: 180: literal string using double-quote instead of single
test/tst.env.js: 183: literal string using double-quote instead of single
test/tst.env.js: 186: literal string using double-quote instead of single
test/tst.env.js: 189: literal string using double-quote instead of single

We can't rewrite all regular expressions easily, since without actual parsing we can't confidently differentiate all of them from division. We can however leverage the fact that many regular expressions start with ^ or end with $, and handle those. ($ is a legal character in an identifier, so someone could have an expression like $/2, but I suspect that that happens much less than regular expressions that need to be JSSTYLED.)

Don't mark "++" at the end of a line as an improper continuation

In this code snippet, the "next" line is marked as an improper continuation:

var i = 0;
var j = {
    next: i++
};

jsstyle should set file encoding to UTF-8

When jsstyle parses a file, it assumes that it's ASCII. This means that when it checks the length of a line, it ends up checking the number of bytes, instead of the number of characters. A better default would be to assume the file is UTF-8. @trentm suggested the following change:

diff --git a/jsstyle b/jsstyle
index 9df33c9..4b3eaca 100755
--- a/jsstyle
+++ b/jsstyle
@@ -210,6 +210,7 @@ my $err_stat = 0;           # exit status
 if ($#ARGV >= 0) {
        foreach my $arg (@ARGV) {
                my $fh = new IO::File $arg, "r";
+               binmode($fh, ":encoding(UTF-8)");
                if (!defined($fh)) {
                        printf "%s: cannot open\n", $arg;
                } else {

I don't know if this should be more configurable, or if always assuming UTF-8 is a fine default for now.

Escape more opening curly brackets in regexes

There are some additional opening curly brackets that newer versions of Perl (like 5.26.1) will complain about with the same message as in #19. We should escape them to fix the warnings, and to avoid fatal problems when Perl 5.30 is used.

Parenthesis grouping around returns is unnec

Unless there is a specific lazy evaluation grouping order, there is no need for parens around return values.

Allow configurable tab width

The calculation of a line not exceeding 80 characters assumes that tabs are set to 8 spaces. It'd be nice if this could be a configurable parameter, such that the line width considers tabs as 4, or even 2, spaces.

Blocks must be indented with tabs, not spaces.

This should be optional with a default

Comments containing urls

Example:

// See: http://www...

Will produce the following error:

missing blank after start comment

I'm guessing it refers to the // in http://

Regexes treated as comments?

Error: missing blank before close comment on:

server.all(/.*/, function (req, res, next) {
  req.sdc = server.clients;
  next();
});

and

server.get(/\/.*/, function (req, res) {
  res.render('index');
});

Strings must be quoted with single quotes.

This should be optional with a default