diff --git a/designs/2019-core-options/README.md b/designs/2019-core-options/README.md new file mode 100644 index 00000000..b4c36717 --- /dev/null +++ b/designs/2019-core-options/README.md @@ -0,0 +1,139 @@ +- Start Date: 2019-05-12 +- RFC PR: https://github.com/eslint/rfcs/pull/22 +- Authors: Toru Nagashima ([@mysticatea](https://github.com/mysticatea)) + +# Configuring core options in Config Files + +## Summary + +This RFC adds several properties into config files to configure core options. People can use config files (including shareable configs!) instead of CLI options in order to configure some linter behavior. + +## Motivation + +We cannot configure some linter's behavior with config files, especially, shareable configs. It's convenient if we can configure those in shareable configs. + +## Detailed Design + +This RFC adds four properties to config files. + +```js +// .eslintrc.js +module.exports = { + noInlineConfig: false, // Corresponds to --no-inline-config + reportUnusedDisableDirectives: false, // Corresponds to --report-unused-disable-directives + verifyOnRecoverableParsingErrors: false, // Corresponds to --verify-on-recoverable-parsing-errors + ignorePatterns: [], // Corresponds to --ignore-pattern + + overrides: [ + { + files: ["*.ts"], + noInlineConfig: false, + reportUnusedDisableDirectives: false, + verifyOnRecoverableParsingErrors: false, + // ignorePatterns: [], // Forbid this to avoid confusion with 'excludedFiles' property. + }, + ], +} +``` + +### § noInlineConfig + +That value can be a boolean value. Default is `false`. + +If `true` then it disables inline directive comments such as `/*eslint-disable*/`. + +If `noInlineConfig` is `true`, `--no-inline-config` was not given, and there are one or more directive comments, then ESLint reports each directive comment as a warning message (`severify=1`). For example, `"'eslint-disable' comment was ignored because your config file has 'noInlineConfig' setting."`. Therefore, end-users can know why directive comments didn't work. + +
+💠Implementation: +

In Linter#_verifyWithoutProcessors method, the linter checks both providedConfig and filenameOrOptions to determine noInlineConfig option. The filenameOrOptions.allowInlineConfig precedences providedConfig.noInlineConfig.

+
+ +### § reportUnusedDisableDirectives + +That value can be a boolean value. Default is `false`. + +If `true` then it reports directive comments like `//eslint-disable-line` when no errors would have been reported on that line anyway. + +This option is different a bit from `--report-unused-disable-directives` CLI option. The `--report-unused-disable-directives` CLI option fails the linting with non-zero exit code (i.e., it's the same behavior as `severity=2`), but this `reportUnusedDisableDirectives` setting doesn't fail the linting (i.e., it's the same behavior as `severity=1`). Therefore, we cannot configure ESLint with `reportUnusedDisableDirectives` as failed by patch releases. + +
+💠Implementation: +
    +
  1. Linter and CLIEngine have options.reportUnusedDisableDirectives. This RFC enhances these options to accept "off", "warn", and "error". Existing false is the same as "off" and existing true is the same as "error".
    2. +
  2. In Linter#_verifyWithoutProcessors method, the linter checks both providedConfig and filenameOrOptions to determine reportUnusedDisableDirectives option. The filenameOrOptions.reportUnusedDisableDirectives precedences providedConfig.reportUnusedDisableDirectives.
    3. +
+
+ +### § verifyOnRecoverableParsingErrors + +That value can be a boolean value. Default is `false`. + +If `true` then it runs rules even if recoverable errors existed. Then it shows both results. + +
+💠Implementation: +

In Linter#_verifyWithoutProcessors method, the linter checks both providedConfig and filenameOrOptions to determine verifyOnRecoverableParsingErrors option. The filenameOrOptions.verifyOnRecoverableParsingErrors precedences providedConfig.verifyOnRecoverableParsingErrors.

+
+ +### § ignorePatterns + +That value can be an array of strings. Default is an empty array. + +This is very similar to `.eslintignore` file. Each value is a file pattern as same as each line of `.eslintignore` file. ESLint compares the path to source code files and the file pattern then it ignores the file if it was matched. The path to source code files is addressed as relative to the entry config file, as same as `files`/`excludedFiles` properties. + +ESLint concatenates all ignore patterns from all of `.eslintignore`, `--ignore-path`, `--ignore-pattern`, and `ignorePatterns`. If there are multiple `ignorePatterns` in a `ConfigArray`, all of them are concatenated. The order is: + +1. The default ignoring. (I.e. `.*`, `node_modules/*`, and `bower_components/*`) +1. `ignorePatterns` in the appearance order in the config array. +1. `--ignore-path` or `.eslintignore`. +1. `--ignore-pattern` + +Negative patterns mean unignoring. For example, `!.*.js` makes ESLint checking JavaScript files which start with `.`. Negative patterns are used to override parent settings. +Also, negative patterns is worthful for shareable configs of some platforms. For example, the config of VuePress can provide the configuration that unignores `.vuepress` directory. + +It disallows `ignorePatterns` property in `overrides` entries in order to avoid confusion with `excludedFiles`. And if a `ignorePatterns` property came from shareable configs in `overrides` entries, ESLint ignores it. This is the same behavior as `root` property. + +The `--no-ignore` CLI option disables `ignorePatterns` as well. + +
+💠Implementation: + +
+ +### § Other options? + +- `extensions` - This RFC doesn't add `extensions` option that corresponds to `--ext` because [#20 "Configuring Additional Lint Targets with `.eslintrc`"](https://github.com/eslint/rfcs/pull/20) is the good successor of that. +- `rulePaths` - This RFC doesn't add `rulePaths` option that corresponds to `--rulesdir` because [#14 (`localPlugins`)](https://github.com/eslint/rfcs/pull/20) is the good successor of that. Because the `rulePaths` doesn't have namespace, shareable configs should not be able to configure that. (Or but it may be useful for some plugins such as `@typescript-eslint/eslint-plugin` in order to replace core rules. I'd like to discuss the replacement way in another place.) +- `format` - This RFC doesn't add `format` option that corresponds to `--format` because it doesn't fit cascading configs. It needs another mechanism. +- `maxWarnings` - This RFC doesn't add `maxWarnings` option that corresponds to `--max-warnings` because it doesn't fit cascading configs. It needs another mechanism. + +## Documentation + +- [Configuring ESLint](https://eslint.org/docs/user-guide/configuring) page should describe new top-level properties. +- [`--no-ignore` document](https://eslint.org/docs/user-guide/command-line-interface#--no-ignore) should mention `ignorePatterns` setting. + +## Drawbacks + +Nothing in particular. + +## Backwards Compatibility Analysis + +No concerns. Currently, unknown top-level properties are a fatal error. + +## Alternatives + +- + +## Related Discussions + +- [eslint/eslint#3529](https://github.com/eslint/eslint/issues/3529) - Set ignore path in .eslintrc +- [eslint/eslint#4261](https://github.com/eslint/eslint/issues/4261) - combine .eslintignore with .eslintrc? +- [eslint/eslint#8824](https://github.com/eslint/eslint/issues/8824) - Allow config to ignore comments that disable rules inline +- [eslint/eslint#9382](https://github.com/eslint/eslint/issues/9382) - Proposal: `reportUnusedDisableDirectives` in config files +- [eslint/eslint#10341](https://github.com/eslint/eslint/issues/10341) - do not ignore files started with `.` by default +- [eslint/eslint#10891](https://github.com/eslint/eslint/issues/10891) - Allow setting ignorePatterns in eslintrc +- [eslint/eslint#11665](https://github.com/eslint/eslint/issues/11665) - Add top-level option for noInlineConfig or allowInlineConfig