Skip to content

OVERVIEW.md

Latest commit

 

History

History
371 lines (258 loc) · 10.9 KB

OVERVIEW.md

File metadata and controls

371 lines (258 loc) · 10.9 KB

Presets

Note: the easiest way to use a preset is with the preset option described below.

You can specifically disable any preset rule by creating a .jscsrc config file and assigning it to null, like so:

{
    "preset": "jquery",
    "requireCurlyBraces": null
}

Friendly packages

Extensions

Installation

jscs can be installed using npm:

npm install jscs -g

To run jscs, you can use the following command from the project root:

jscs path[ path[...]]

You can also pipe input into jscs:

cat myfile.js | jscs

CLI

Some CLI options can be put in your .jscsrc as well (such as esnext).

--fix (-x)

Will apply fixes to all supported style rules. (Currently whitespace rules, EOF rule, and validateIndentation)

jscs path[ path[...]] --fix

--auto-configure

Presents a walkthrough that allows you to generate a JSCS configuration by choosing a preset and handling violated rules.

jscs --auto-configure path

path can be a file or directory to check the presets against

--config (-c)

Allows to define path to the config file.

jscs path[ path[...]] --config=./.config.json

If there is no --config option specified, jscs it will consequentially search for jscsConfig option in package.json file then for .jscsrc (which is a just JSON with comments) and .jscs.json files in the current working directory then in nearest ancestor until it hits the system root.

--preset (-p)

If defined will use predefined rules for specific code style.

jscs path[ path[...]] --preset=jquery

In order to add/remove preset rules you will need to create a .jscsrc config file.

--reporter (-r)

jscs itself provides six reporters: checkstyle, console, inline, inlinesingle, junit and text.

jscs path[ path[...]] --reporter=console

But you also can specify your own reporter, since this flag accepts relative or absolute paths too.

jscs path[ path[...]] --reporter=./some-dir/my-reporter.js

--esnext (-e)

Attempts to parse your code as ES6 using the harmony version of the esprima parser. Please note that this is currently experimental, and will improve over time.

--esprima (-s)

Attempts to parse your code with a custom Esprima version.

jscs path[ path[...]] --esprima=esprima-fb

--error-filter (-f)

The path to a module that determines whether or not an error should be reported.

jscs path[ path[...]] --error-filter=path/to/my/module.js

--no-colors (-n)

Clean output without colors.

--max-errors (-m)

Set the maximum number of errors to report

--help (-h)

Outputs usage information.

--verbose (-v)

Prepends the name of the offending rule to all error messages.

--version (-V)

Outputs version of jscs.

Options

plugins

Paths to load plugins. See the wiki page for more details about the Plugin API

Values: Array of NPM package names or paths

"plugins": ["jscs-plugin", "./lib/project-jscs-plugin"]

additionalRules

Path to load additional rules

Type: Array

Values: Array of file matching patterns

Example

"additionalRules": ["project-rules/*.js"]

preset

Extends defined rules with preset rules.

Type: String

Values: "airbnb", "crockford", "google", "jquery", "mdcs", "node-style-guide", "wikimedia", wordpress, "yandex"

Example

"preset": "jquery"

You can specifically disable any preset rule by assigning it to null, like so:

{
    "preset": "jquery",
    "requireCurlyBraces": null
}

excludeFiles

Disables style checking for specified paths declared with glob patterns.

Type: Array

Values: Array of file matching patterns

Example

"excludeFiles": ["node_modules/**", "src/!(bar|foo)"]

fileExtensions

Changes the set of file extensions that will be processed.

Type: Array or String or "*"

Values: A single file extension or an Array of file extensions, beginning with a .. The matching is case insensitive. If "*" is provided, all files regardless of extension will match.

Example

"fileExtensions": [".js", ".jsx"]

Default

"fileExtensions": [".js"]

maxErrors

Set the maximum number of errors to report

Type: Number

Default: Infinity

Example

"maxErrors": 10

esnext

Attempts to parse your code as ES6 using the harmony version of the esprima parser.

Type: Boolean

Value: true

Example

"esnext": true

verbose

Prepends the name of the offending rule to all error messages.

Type: Boolean

Default: false

Example

"verbose": true

esprimaOptions

Custom options to be passed to esprima.parse(code, options)

Type: Object

Default: { "tolerant": true }

Example

"esprimaOptions": { "tolerant": true }

errorFilter

A filter function that determines whether or not to report an error. This will be called for every found error.

Type: String

Example

"errorFilter": "path/to/my/filter.js"

See how to define an error filter.

Error Suppression

Disabling a Rule

You can specifically disable any rule by ommitting it from your .jscsrc config or by assigning it to null, like so:

{
    "preset": "jquery",
    "requireCurlyBraces": null
}

Inline Comments

You can disable and re-enable rules inline with two special comments: // jscs:disable and // jscs:enable. Spacing in these comments is fairly lenient. All of the following are equivalent:

/* jscs: enable */
// jscs: enable

You can use them to disable rules in several ways.

Disabling All Rules

Simply using // jscs:disable or // jscs:enable will disable all rules.

var a = b;
// jscs:disable
var c = d; // all errors on this line will be ignored
// jscs:enable
var e = f; // all errors on this line will be reported

Disabling Specific Rules

Including a comma separated list of rules to modify after // jscs:disable or // jscs:enable will modify only those rules.

// jscs:disable requireCurlyBraces
if (x) y(); // all errors from requireCurlyBraces on this line will be ignored
// jscs:enable requireCurlyBraces
if (z) a(); // all errors, including from requireCurlyBraces, on this line will be reported

You can enable all rules after disabling a specific rule, and that rule becomes re-enabled as well.

// jscs:disable requireCurlyBraces
if (x) y(); // all errors from requireCurlyBraces on this line will be ignored
// jscs:enable
if (z) a(); // all errors, even from requireCurlyBraces, will be reported

You can disable multiple rules at once and progressively re-enable them.

// jscs:disable requireCurlyBraces, requireDotNotation
if (x['a']) y(); // all errors from requireCurlyBraces OR requireDotNotation on this line will be ignored
// jscs:enable requireCurlyBraces
if (z['a']) a(); // all errors from requireDotNotation, but not requireCurlyBraces, will be ignored
// jscs:enable requireDotNotation
if (z['a']) a(); // all errors will be reported

Versioning & Semver

We recommend installing JSCS via NPM using ^, or ~ if you want more stable releases.

Semver (http://semver.org/) dictates that breaking changes be major version bumps. In the context of a linting tool, a bug fix that causes more errors to be reported can be interpreted as a breaking change. However, that would require major version bumps to occur more often than can be desirable. Therefore, as a compromise, we will only release bug fixes that cause more errors to be reported in minor versions.

Below you fill find our versioning strategy, and what you can expect to come out of a new JSCS release.

  • Patch release:
    • A bug fix in a rule that causes JSCS to report less errors.
    • Docs, refactoring and other "invisible" changes for user;
  • Minor release:
    • Any preset changes.
    • A bug fix in a rule that causes JSCS to report more errors.
    • New rules or new options for existing rules that don't change existing behavior.
    • Modifying rules so they report less errors, and don't cause build failures.
  • Major release:
    • Purposefully modifying existing rules so that they report more errors or change the meaning of a rule.
    • Any architectural changes that could cause builds to fail.