Skip to content
Permalink
Browse files

Breaking: Plugins envs and config removal (fixes #4782, fixes #4952)

  • Loading branch information...
nzakas committed Jan 8, 2016
1 parent c52c11a commit b28a19d1b708e42bf54c0afc6df363b2c3d250a3
@@ -8,7 +8,7 @@ The easiest way to start creating a plugin is to use the [Yeoman generator](http

### Rules in Plugins

If your plugin has rules, then it must export an object with a `rules` property. This `rules` property should be an object containing a key-value mapping of rule ID to rule. The rule ID does not have to follow any naming convention (so it can just be `dollar-sign`, for instance).
Plugins can expose additional rules for use in ESLint. To do so, the plugin must export a `rules` object containing a key-value mapping of rule ID to rule. The rule ID does not have to follow any naming convention (so it can just be `dollar-sign`, for instance).

```js
module.exports = {
@@ -20,6 +20,32 @@ module.exports = {
};
```

To use the rule in ESLint, you would use the unprefixed plugin name, followed by a slash, followed by the rule name. So if this plugin were named `eslint-plugin-myplugin`, then you would set the environment in your configuration to be `"myplugin/dollar-sign"`.


### Environments in Plugins

Plugins can expose additional environments for use in ESLint. To do so, the plugin must export an `environments` object. The keys of the `environments` object are the names of the different environments provided and the values are the environment settings. For example:

```js
module.exports = {
environments: {
jquery: {
globals: {
$: false
}
}
}
};
```

There's a `jquery` environment defined in this plugin. To use the environment in ESLint, you would use the unprefixed plugin name, followed by a slash, followed by the environment name. So if this plugin were named `eslint-plugin-myplugin`, then you would set the environment in your configuration to be `"myplugin/jquery"`.

Plugin environments can define the following objects:

1. `globals` - acts the same `globals` in a configuration file. The keys are the names of the globals and the values are `true` to allow the global to be overwritten and `false` to disallow.
1. `parserOptions` - acts the same as `parserOptions` in a configuration file.

### Processors in Plugins

You can also create plugins that would tell ESLint how to process files other than JavaScript. In order to create a processor, object that is exported from your module has to conform to the following interface:
@@ -58,25 +84,6 @@ array corresponds to the part that was returned from the `preprocess` method. Th
You can have both rules and processors in a single plugin. You can also have multiple processors in one plugin.
To support multiple extensions, add each one to the `processors` element and point them to the same object.

### Default Configuration for Plugins

You can provide default configuration for the rules included in your plugin by modifying
exported object to include `rulesConfig` property. `rulesConfig` follows the same pattern as
you would use in your .eslintrc config `rules` property, but without plugin name as a prefix.

```js
module.exports = {
rules: {
"myFirstRule": require("./lib/rules/my-first-rule"),
"mySecondRule": require("./lib/rules/my-second-rule")
},
rulesConfig: {
"myFirstRule": 1,
"mySecondRule": [2, "on"]
}
};
```

### Peer Dependency

To make clear that the plugin requires ESLint to work correctly you have to declare ESLint as a `peerDependency` in your `package.json`.
@@ -81,6 +81,7 @@ An environment defines global variables that are predefined. The available envir
* `browser` - browser global variables.
* `node` - Node.js global variables and Node.js scoping.
* `commonjs` - CommonJS global variables and CommonJS scoping (use this for browser-only code that uses Browserify/WebPack).
* `es6` - enable all ECMAScript 6 features except for modules.
* `worker` - web workers global variables.
* `amd` - defines `require()` and `define()` as global variables as per the [amd](https://github.com/amdjs/amdjs-api/wiki/AMD) spec.
* `mocha` - adds all of the Mocha testing global variables.
@@ -100,7 +101,6 @@ An environment defines global variables that are predefined. The available envir
* `atomtest` - Atom test helper globals.
* `embertest` - Ember test helper globals.
* `webextensions` - WebExtensions globals.
* `es6` - enable all ECMAScript 6 features except for modules.
* `greasemonkey` - GreaseMonkey globals.

These environments are not mutually exclusive, so you can define more than one at a time.
@@ -150,6 +150,42 @@ And in YAML:
node: true
```

If you want to use an environment from a plugin, be sure to specify the plugin name in the `plugins` array and the use the unprefixed plugin name, followed by a slash, followed by the environment name. For example:

```json
{
"plugins": ["example"],
"env": {
"example/custom": true
}
}
```

Or in a `package.json` file

```json
{
"name": "mypackage",
"version": "0.0.1",
"eslintConfig": {
"plugins": ["example"],
"env": {
"example/custom": true
}
}
}
```

And in YAML:

```yaml
---
plugins:
- example
env:
example/custom: true
```

## Specifying Globals

The [no-undef](../rules/no-undef.md) rule will warn on variables that are accessed but not defined within the same file. If you are using global variables inside of a file then it's worthwhile to define those globals so that ESLint will not warn about their usage. You can define global variables either using comments inside of a file or in the configuration file.
@@ -265,7 +265,6 @@ ESLint 2.0.0 removes these conflicting defaults, and so you may begin seeing lin
[`no-multiple-empty-lines`]: ../rules/no-multiple-empty-lines
[`func-style`]: ../rules/func-style


## SourceCode constructor (Node API) changes

`SourceCode` constructor got to handle Unicode BOM.
@@ -291,4 +290,10 @@ var sourceCode = new SourceCode(text, ast);

## Rule Changes

* [strict](strict.md) - defaults to `"safe"`
* [`strict`](../rules/strict.md) - defaults to `"safe"` (previous default was `"function"`)

## Plugins No Longer Have Default Configurations

Prior to v2.0.0, plugins could specify a `rulesConfig` for the plugin. The `rulesConfig` would automatically be applied whenever someone uses the plugin, which is the opposite of what ESLint does in every other situation (where nothing is on by default). To bring plugins behavior in line, we have removed support for `rulesConfig` in plugins.

**To address:** If you are using a plugin in your configuration file, you will need to manually enable the plugin rules in the configuration file.
@@ -29,7 +29,7 @@ var fs = require("fs"),
eslint = require("./eslint"),
IgnoredPaths = require("./ignored-paths"),
Config = require("./config"),
util = require("./util"),
Plugins = require("./config/plugins"),
fileEntryCache = require("file-entry-cache"),
globUtil = require("./util/glob-util"),
SourceCodeFixer = require("./util/source-code-fixer"),
@@ -78,63 +78,34 @@ var DEFAULT_PARSER = require("../conf/eslint.json").parser;
//------------------------------------------------------------------------------

var defaultOptions = {
configFile: null,
baseConfig: false,
rulePaths: [],
useEslintrc: true,
envs: [],
globals: [],
rules: {},
extensions: [".js"],
ignore: true,
ignorePath: null,
parser: DEFAULT_PARSER,
cache: false,
// in order to honor the cacheFile option if specified
// this option should not have a default value otherwise
// it will always be used
cacheLocation: "",
cacheFile: ".eslintcache",
fix: false,
allowInlineConfig: true,
cwd: process.cwd()
},
loadedPlugins = Object.create(null);
configFile: null,
baseConfig: false,
rulePaths: [],
useEslintrc: true,
envs: [],
globals: [],
rules: {},
extensions: [".js"],
ignore: true,
ignorePath: null,
parser: DEFAULT_PARSER,
cache: false,
// in order to honor the cacheFile option if specified
// this option should not have a default value otherwise
// it will always be used
cacheLocation: "",
cacheFile: ".eslintcache",
fix: false,
allowInlineConfig: true,
cwd: process.cwd()
};

//------------------------------------------------------------------------------
// Helpers
//------------------------------------------------------------------------------

debug = debug("eslint:cli-engine");

/**
* Load the given plugins if they are not loaded already.
* @param {string[]} pluginNames An array of plugin names which should be loaded.
* @returns {void}
*/
function loadPlugins(pluginNames) {
if (pluginNames) {
pluginNames.forEach(function(pluginName) {
var pluginNamespace = util.getNamespace(pluginName),
pluginNameWithoutNamespace = util.removeNameSpace(pluginName),
pluginNameWithoutPrefix = util.removePluginPrefix(pluginNameWithoutNamespace),
plugin;

if (!loadedPlugins[pluginNameWithoutPrefix]) {
debug("Load plugin " + pluginNameWithoutPrefix);

plugin = require(pluginNamespace + util.PLUGIN_NAME_PREFIX + pluginNameWithoutPrefix);
// if this plugin has rules, import them
if (plugin.rules) {
rules.import(plugin.rules, pluginNameWithoutPrefix);
}

loadedPlugins[pluginNameWithoutPrefix] = plugin;
}
});
}
}

/**
* It will calculate the error and warning count for collection of messages per file
* @param {Object[]} messages - Collection of messages
@@ -193,6 +164,7 @@ function processText(text, configHelper, filename, fix, allowInlineConfig) {
stats,
fileExtension = path.extname(filename),
processor,
loadedPlugins,
fixedResult;

if (filename) {
@@ -202,7 +174,12 @@ function processText(text, configHelper, filename, fix, allowInlineConfig) {
filename = filename || "<text>";
debug("Linting " + filename);
config = configHelper.getConfig(filePath);
loadPlugins(config.plugins);

if (config.plugins) {
Plugins.loadAll(config.plugins);
}

loadedPlugins = Plugins.getAll();

for (var plugin in loadedPlugins) {
if (loadedPlugins[plugin].processors && Object.keys(loadedPlugins[plugin].processors).indexOf(fileExtension) >= 0) {
@@ -510,11 +487,7 @@ CLIEngine.prototype = {
* @returns {void}
*/
addPlugin: function(name, pluginobject) {
var pluginNameWithoutPrefix = util.removePluginPrefix(util.removeNameSpace(name));
if (pluginobject.rules) {
rules.import(pluginobject.rules, pluginNameWithoutPrefix);
}
loadedPlugins[pluginNameWithoutPrefix] = pluginobject;
Plugins.define(name, pluginobject);
},

/**
@@ -1,7 +1,7 @@
/**
* @fileoverview Responsible for loading config files
* @author Seth McLaughlin
* @copyright 2014 Nicholas C. Zakas. All rights reserved.
* @copyright 2014-2016 Nicholas C. Zakas. All rights reserved.
* @copyright 2014 Michael McLaughlin. All rights reserved.
* @copyright 2013 Seth McLaughlin. All rights reserved.
* See LICENSE in root directory for full license.
@@ -15,7 +15,7 @@
var path = require("path"),
ConfigOps = require("./config/config-ops"),
ConfigFile = require("./config/config-file"),
util = require("./util"),
Plugins = require("./config/plugins"),
FileFinder = require("./file-finder"),
debug = require("debug"),
userHome = require("user-home"),
@@ -28,12 +28,6 @@ var path = require("path"),

var PERSONAL_CONFIG_DIR = userHome || null;

//------------------------------------------------------------------------------
// Private
//------------------------------------------------------------------------------

var loadedPlugins = Object.create(null);

//------------------------------------------------------------------------------
// Helpers
//------------------------------------------------------------------------------
@@ -78,47 +72,6 @@ function loadConfig(configToLoad) {
return config;
}

/**
* Load configuration for all plugins provided.
* @param {string[]} pluginNames An array of plugin names which should be loaded.
* @returns {Object} all plugin configurations merged together
*/
function getPluginsConfig(pluginNames) {
var pluginConfig = {};

pluginNames.forEach(function(pluginName) {
var pluginNamespace = util.getNamespace(pluginName),
pluginNameWithoutNamespace = util.removeNameSpace(pluginName),
pluginNameWithoutPrefix = util.removePluginPrefix(pluginNameWithoutNamespace),
plugin = {},
rules = {};

if (!loadedPlugins[pluginNameWithoutPrefix]) {
try {
plugin = require(pluginNamespace + util.PLUGIN_NAME_PREFIX + pluginNameWithoutPrefix);
loadedPlugins[pluginNameWithoutPrefix] = plugin;
} catch (err) {
debug("Failed to load plugin configuration for " + pluginNameWithoutPrefix + ". Proceeding without it.");
plugin = { rulesConfig: {}};
}
} else {
plugin = loadedPlugins[pluginNameWithoutPrefix];
}

if (!plugin.rulesConfig) {
plugin.rulesConfig = {};
}

Object.keys(plugin.rulesConfig).forEach(function(item) {
rules[pluginNameWithoutPrefix + "/" + item] = plugin.rulesConfig[item];
});

pluginConfig = ConfigOps.merge(pluginConfig, rules);
});

return {rules: pluginConfig};
}

/**
* Get personal config object from ~/.eslintrc.
* @returns {Object} the personal config object (empty object if there is no personal config)
@@ -252,8 +205,7 @@ function Config(options) {
Config.prototype.getConfig = function(filePath) {
var config,
userConfig,
directory = filePath ? path.dirname(filePath) : this.options.cwd,
pluginConfig;
directory = filePath ? path.dirname(filePath) : this.options.cwd;

debug("Constructing config for " + (filePath ? filePath : "text"));

@@ -301,17 +253,11 @@ Config.prototype.getConfig = function(filePath) {
// Step 8: Merge in command line plugins
if (this.options.plugins) {
debug("Merging command line plugins");
pluginConfig = getPluginsConfig(this.options.plugins);
Plugins.loadAll(this.options.plugins);
config = ConfigOps.merge(config, { plugins: this.options.plugins });
}

// Step 9: Merge in plugin specific rules in reverse
if (config.plugins) {
pluginConfig = getPluginsConfig(config.plugins);
config = ConfigOps.merge(pluginConfig, config);
}

// Step 10: Apply environments to the config if present
// Step 9: Apply environments to the config if present
if (config.env) {
config = ConfigOps.applyEnvironments(config);
}
Oops, something went wrong.

0 comments on commit b28a19d

Please sign in to comment.
You can’t perform that action at this time.