JSCS Tutorial

发表于 2015-09-01 更新于 2018-06-23 分类于 Node.js

Overview

JSCS 已经合并到了ESLint！
JSCS 是一个能够指导你对代码风格进行检查和格式化的工具。

Presets

注意：最简单的方式就是使用一个预先设置好的选项，如下：

你可以在创建的配置文件.jscsrc中将任意一个规则禁用，只需要赋值null或者false，像这样：

{
    "preset": "jquery",
    "requireCurlyBraces": null // or false
}

Friendly packages

Atom plugin: https://atom.io/packages/linter-jscs
Brackets Extension: https://github.com/globexdesigns/brackets-jscs
Grunt task: https://github.com/jscs-dev/grunt-jscs/
Gulp task: https://github.com/jscs-dev/gulp-jscs/
Overcommit Git pre-commit hook manager: https://github.com/brigade/overcommit/
SublimeText 3 Plugin: https://github.com/SublimeLinter/SublimeLinter-jscs/
Syntastic VIM Plugin: https://github.com/scrooloose/syntastic/.../syntax_checkers/javascript/jscs.vim/
Web Essentials for Visual Studio 2013: https://github.com/madskristensen/WebEssentials2013/
IntelliJ IDEA, RubyMine, WebStorm, PhpStorm, PyCharm plugin: https://www.jetbrains.com/webstorm/help/jscs.html
Visual Studio Code extension: https://github.com/microsoft/vscode-jscs

Extensions

A TeamCity reporter: https://github.com/wurmr/jscs-teamcity-reporter
JSDoc rules extension: https://github.com/jscs-dev/jscs-jsdoc

Installation

jscs可以使用npm来进行安装：

1	npm install jscs -g

你可以使用以下命令从项目的根路径运行：

1	jscs path[ path[...]]

你还可以通过管道输出到jscs:

1	cat myfile.js \| jscs

Programmatic Usage

jscs 可以在你的程序代码里面直接使用：

1
2
3

var Checker = require("jscs");
var checker = new Checker();
checker.registerDefaultRules();

你可以配置检查器实例去使用指定的选项，或者预设的值：

// Configure the checker with an options object
checker.configure({
    "requireCurlyBraces": [
        "if",
        "else",
        "for"
    ]
});

// Use the jQuery preset
checker.configure({
    preset: "jquery"
});

// Use the Google preset, but override or remove some options
checker.configure({
    preset: "google",
    disallowMultipleLineBreaks: null, // or false
    validateIndentation: "\t"
});

要检查一个字符串类型的代码，通过使用checkString方法：

1 2	var results = checker.checkString(stringOfCode); var errors = results.getErrorList();

这个results对象可以获取每个错误的描述信息：

results.getErrorList().forEach(function(error) {
    var colorizeOutput = true;
    console.log(results.explainError(error, colorizeOutput) + "\n");
});

CLI

某些CLI选项也可以放到你的.jscsrc文件中（比如preset）。
下面的这些选项已经从3.0中移除掉了(esnext默认就是激活的).

–esnext (-e)
–esprima (-s)

这个verbose标记也在3.0被移除了，因为它默认就被开启的(所以你知道哪些规则是错误的)。

–fix (-x)

可以修复所有支持的风格。

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

–auto-configure

自动生成一个你选择的预置规则文件：

1	jscs --auto-configure path

path 可以是文件或者目录。

–config (-c)

允许指定一个具体路径的配置文件：

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

若这个–config没有指定，jscs会去package.json文件中通过jscsConfig选项来找.jscsrc和.jscs.json文件。

–preset (-p)

指定预定义的代码风格规则：

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

你需要穿点一个.jscsrc配置文件来添加/删除这些规则。

–extract

使用这个选项可以检查嵌入式的js代码：

1	jscs path[ path[...]] --extract *.html

如果需要的话可以设置多个：

1	jscs path[ path[...]] --extract .html --extract .htm

目前，只支持html格式的，但是不能够自动修复。

–reporter (-r)

jscs 提供了8种方式的报告: checkstyle, console, inline, inlinesingle, junit, text, unix and json.

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

还可以指定自己的路径文件：

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

–error-filter (-f)

错误过滤器：

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

–no-colors (-n)

无颜色输出。

–max-errors (-m)

设置报告的最大错误数量。（-1表示报告所有的错误）

–help (-h)

输出使用信息。

–version (-V)

输出jscs版本信息。

Options

以下选项已经在3.0版本中被移除（esnext默认是激活的）。

esnext: Attempts to parse your code as ES6+, JSX, and Flow using babylon as the underlying parser.
esprima: Attempts to parse your code with a custom Esprima version.
esprimaOptions: Custom options to be passed to esprima.parse(code, options)

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

plugins

从指定的多个路径加载插件。详细信息查看Plugin API
Values: Array of NPM package names or paths

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

additionalRules

额外规则的路径。
Type: Array
Values: Array of file matching patterns
Example

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

preset

集成预定义的规则。
Type: String

Values: 你可以选择一个默认的规则：”airbnb”, “crockford”, “google”, “jquery”, “mdcs”, “node-style-guide”, “wikimedia”, “wordpress”, “idiomatic”.
或者从你的本地加载。
Example

"preset": "jquery"
"preset": "./path-to-your-preset"

// If your preset called "jscs-your-preset-node_modules-path"
// You can either define full name or omit "jscs-" prefix -
"preset": "your-preset-node_modules-path"

你也可以通过指定null或者false来禁用指定的预设规则。

excludeFiles

排除不需要检查的文件。
Type: Array

Values: Array of file matching patterns

Example

1 2	// Use `"!foo"` to specifically include a file/folder "excludeFiles": ["folder_to_exclude/**", "src/!(bar\|foo)"]

Default
这个 .git 和 node_modules 文件夹默认被排除。

fileExtensions

改变文件的扩展类型。
type: Array or String or “*”

Values: 单个文件后缀或者数组，以.开头，匹配不区分大小写，如果是”*”表示匹配所有的文件。
Example

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

Default
.js 后缀的文件是默认被处理的格式。

extract

设置嵌入式代码被提取的文件格式。

Type: Array or Boolean

Values: Array of file matching patterns

js代码提取不会匹配fileExtensions 或者 excludeFiles设置过的。目前只支持html格式的。

Example

“extract”: [“.htm”, “.html”]
Value true

如果设置的值为true，将从.htm,.html或者.xhtml后缀的文件提取代码。

maxErrors

设置报告的最大错误数量（通过设置-1或者null输出所有的错误）。如果fix属性被激活则忽略。

Type: Number|null

Default: 50

Example

// Report only the first 10 errors
"maxErrors": 10

// Report all errors
"maxErrors": -1
"maxErrors": null

fix

将修复所有支持的代码规则。

Type: Boolean|null

Default: false

es3

Use ES3 reserved words.

Type: Boolean

Value: true

Example

“es3”: true

errorFilter

错误过滤器，根据返回的值来决定是否报告这个错误。

Type: String

Example

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

See how to define an error filter.

Error Suppression

Disabling a Rule

通过在你的.jscsrc配置里面指定null可以禁用规则。

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

Inline Comments

你也可以通过注释的写法来禁用或者激活：

1 2	/* jscs: enable */ // jscs: enable

你可以同时使用以上几种方式来禁用规则。

Disabling All Rules

The placement of the special comments will disable or enable the checking of all rules against the code that appears after the comments。

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

通过行注释jscs:disable来禁用指定的规则或者jscs:enable来激活规则。

// 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

Disabling Specific Rules For a Single Line

通过单行注释也可以进行规则：

1 2	if (x) y(); // jscs:ignore requireCurlyBraces if (z) a();

你可以在禁用规则之后在激活所有的规则。

// 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

你也可以禁用多个规则后在逐步重新激活规则。

// 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

Disabling rule checks on the entire file

通过在文件顶部添加注释来禁用所有的规则。

1	// jscs:disable

As the comments are applicable only to the file they are placed in there is no requirement to put the special comment // jscs:enable at the end of the file.

The same concept is applicable to disable only specific rules in the file. So instead of // jscs:disable, you can put // jscs:disable requireCurlyBraces to disable a single rule or // jscs:disable requireCurlyBraces, requireDotNotation to disable multiple rules

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.