mimosa-jscs
This is a Mimosa module for linting Javascript code using JSCS.
Installation
Add jscs
to your Mimosa project's list of modules and build the
project. This will download the latest version of mimosa-jscs
from
npmjs.org.
Configuration
To customize the linting you need to add a jscs
configuration to
your project's mimosa-config
. mimosa-jscs
is configured in the
same way as other Mimosa linting tools such as
mimosa-jshint. The
configuration options and the default values are as follows:
jscs: {
exclude: [],
compiled: true,
copied: true,
vendor: false,
executeAfterCompile: true,
configFile: undefined,
rules: {}
}
Which files are linted are controlled by the jscs.exclude
,
jscs.compiled
, jscs.copied
, and jscs.vendor
options. These
options work just like the corresponding options for the
JSHint Mimosa plugin.
executeAfterCompile
determines whether JSCS runs on code before
or after it is compiled. This defaults to true
which means that
JSCS runs on compiled code. So, for instance, it would not run on
CoffeeScript, instead it would run on the compiled JavaScript. You
may find you want to run on pre-compiled code. Some compilers, like
Babel will transform the style of the code
when it compiles it. If running on the compiled output of Babel,
JSCS will have many problems that cannot be avoided.
To configure JSCS, set either the jscs.rules
property, the
jscs.configFile
property, or both. JSCS configuration options are
described in detail in the JSCS documentation. For
example, adding the following to your Mimosa config will make JSCS
check that files end with a newline:
jscs: {
rules: {
requireLineFeedAtFileEnd: true
}
}
mimosa-jscs
will pass the configuration to JSCS without validating
its contents. The following configuration options have been verified
to work:
- Individual rules.
preset
.additionalRules
. Rule paths are relative to the project root.excludeFiles
. In addition to thejscs.exclude
property described above,mimosa-jscs
also supports excluding files usingexcludeFiles
in the JSCS configuration. This can come in handy if you want to share a JSCS configuration file between Mimosa and (for instance) an editor or IDE. Paths are relative to the project root.maxErrors
. In build mode,maxErrors
is the maximum number of reported violations per build. In watch mode,maxErrors
is per file.errorFilter
. Paths are relative to the project root.esnext
.plugins
. Paths are relative to the project root.verbose
.
The option fileExtensions
is currently ignored.
jscs.configFile
is the file name of a JSCS configuration file,
absolute or relative to the project's root. In contrast to running
JSCS from the command line, mimosa-jscs
will not search other
directories outside of your project for a configuration file. In
particular, it will not search your home directory or the project
directory's ancestors for a file named .jscsrc
or .jscs.json
. This
is to make building independent of external files not part of the
Mimosa project.
mimosa-jscs
reads configuration files the same way as JSCS does,
which means that the file format is determined from the file name:
- If the file extension is
.js
the file is read as a Node module using Node's require. - If the file name is
package.json
the file is standard JSON and the configuration is in a property calledjscsConfig
. - If the file name is anything else with the extension
.json
the file is standard JSON. - Otherwise the file is commented JSON. Comments are standard Javascript comments and are stripped using strip-json-comments.
Both configFile
and rules
can be specified at the same time. In
that case the configuration passed to JSCS will be the configuration
found in the file overridden by anything found in rules
. Note that
in JSCS rules always override presets meaning that a rule configured
in the file will still override a preset configured in rules
.
Examples
To lint your Javascript using JSCS' Crockford preset, add the following to your project's Mimosa configuration:
jscs: {
rules: {
preset: 'crockford',
}
}
The following configuration will lint according to the Crockford preset and also check that all comments starts with a capital letter:
jscs: {
rules: {
preset: 'crockford',
requireCapitalizedComments: true
}
}
To disable a rule, set it to null
(this is standard JSCS behavior).
The following configration will lint using the Crockford preset but
disable indentation checking:
jscs: {
rules: {
preset: 'crockford',
validateIndentation: null
}
}
The following module configuration will read the JSCS configuration
from the project's package.json
:
jscs: {
configFile: 'package.json'
}
To lint using the Crockford preset, add the following to your
package.json
:
jscsConfig: {
preset: 'crockford'
}
Compatibility
By default mimosa-jscs
uses the latest version of JSCS that is
compatible with a version it has been tested with. Compatibility is
according to semver.
JSCS' approach to versioning is explained in the JSCS documentation. In short, changes in rules and presets that cause more (or less) code style violations to be reported are not considered breaking changes. To have better control of your JSCS linting you may want to use a specific version of JSCS.
To use a specific JSCS version add JSCS as dependency to your project. For example, to use JSCS version 1.8.0 type the following in your project root:
npm install --save-dev --save-exact jscs@1.8.0
If you try to use mimosa-jscs
with a version of JSCS it has not been
verified to be compatible with, npm install
will fail with the
following message:
npm ERR! peerinvalid The package jscs does not satisfy its siblings' peerDependencies requirements!
mimosa-jscs
has been verified to work with the following JSCS
versions: 1.3.0,
1.4.0,
1.4.3,
1.4.4,
1.4.5,
1.5.1,
1.5.2,
1.5.3,
1.5.4,
1.5.6,
1.5.7,
1.5.8,
1.5.9,
1.6.0,
1.6.1,
1.6.2,
1.7.0,
1.7.1,
1.7.2,
1.7.3,
1.8.0,
1.8.1,
1.9.0, 1.10.0,
1.11.0, 1.11.1, 1.11.2, 1.11.3, 1.12.0, 1.13.0, 1.13.1, and 2.0.0.
This module has been tested with Mimosa 2.3.x but should work with other versions of Mimosa as well.
Version history
-
3.0.0 Added JSCS v2.0.0 to list of compatible versions. Starting with version 2.0.0 the API
mimos-jscs
uses is part of JSCS' public API and is covered by the semver versioning rules. This makes it much easier to manage compatibility,mimosa-jscs
should now be compatible with any JSCS version 2.x.y. Updated the documentation accordingly.Major version bump because of JSCS' major version bump which may break compatibility.
-
2.3.0 Added JSCS v1.13.0 and v1.13.1 to list of compatible versions.
-
2.2.0 Added configuration option
executeAfterCompile
that makes it possible to configure if style of compiled resources are checked before or after compilation. Useful when compiling with Babel. Requested and implemented by dbashford. -
2.1.0 Added JSCS v1.12.0 to list of compatible versions. Removed Mimosa
placeholder
config property to be compatible with upcoming Mimosa v3.0.0. Minor documentation updates. -
2.0.0 JSCS is now an npm peer dependency which makes it possible for a user to choose JSCS version. Created unit tests for compatibility with JSCS versions from 1.3.0 up to 1.11.3.
package.json
contains a whitelist listing compatible versions.Major version bump because of the switch to a peer dependency for JSCS.
-
1.1.0 Support JSCS option excludeFiles.
-
1.0.4 Add documentation and test for esnext, additionalRules options.
-
1.0.3 Support for the maxErrors option.
-
1.0.2 Warn if neither rules nor config file is configured.
-
1.0.1 Cosmetic changes.
-
1.0.0 First functional version. Runs JSCS, loads configuration from mimosa config or file, configuration mimics mimosa-jshint.