eslint 8.0.0-beta.0 → 8.0.0

package/lib/rules/space-before-blocks.js

@@ -40,7 +40,6 @@ module.exports = {
 
         docs: {
             description: "enforce consistent spacing before blocks",
-            category: "Stylistic Issues",
             recommended: false,
             url: "https://eslint.org/docs/rules/space-before-blocks"
         },
@@ -108,13 +107,25 @@ module.exports = {
          * Checks whether the spacing before the given block is already controlled by another rule:
          * - `arrow-spacing` checks spaces after `=>`.
          * - `keyword-spacing` checks spaces after keywords in certain contexts.
+         * - `switch-colon-spacing` checks spaces after `:` of switch cases.
          * @param {Token} precedingToken first token before the block.
          * @param {ASTNode|Token} node `BlockStatement` node or `{` token of a `SwitchStatement` node.
          * @returns {boolean} `true` if requiring or disallowing spaces before the given block could produce conflicts with other rules.
          */
         function isConflicted(precedingToken, node) {
-            return astUtils.isArrowToken(precedingToken) ||
-                astUtils.isKeywordToken(precedingToken) && !isFunctionBody(node);
+            return (
+                astUtils.isArrowToken(precedingToken) ||
+                (
+                    astUtils.isKeywordToken(precedingToken) &&
+                    !isFunctionBody(node)
+                ) ||
+                (
+                    astUtils.isColonToken(precedingToken) &&
+                    node.parent &&
+                    node.parent.type === "SwitchCase" &&
+                    precedingToken === astUtils.getSwitchCaseColonToken(node.parent, sourceCode)
+                )
+            );
         }
 
         /**

package/lib/rules/space-before-function-paren.js

@@ -20,7 +20,6 @@ module.exports = {
 
         docs: {
             description: "enforce consistent spacing before `function` definition opening parenthesis",
-            category: "Stylistic Issues",
             recommended: false,
             url: "https://eslint.org/docs/rules/space-before-function-paren"
         },

package/lib/rules/space-in-parens.js

@@ -16,7 +16,6 @@ module.exports = {
 
         docs: {
             description: "enforce consistent spacing inside parentheses",
-            category: "Stylistic Issues",
             recommended: false,
             url: "https://eslint.org/docs/rules/space-in-parens"
         },

package/lib/rules/space-infix-ops.js

@@ -16,7 +16,6 @@ module.exports = {
 
         docs: {
             description: "require spacing around infix operators",
-            category: "Stylistic Issues",
             recommended: false,
             url: "https://eslint.org/docs/rules/space-infix-ops"
         },

package/lib/rules/space-unary-ops.js

@@ -20,7 +20,6 @@ module.exports = {
 
         docs: {
             description: "enforce consistent spacing before or after unary operators",
-            category: "Stylistic Issues",
             recommended: false,
             url: "https://eslint.org/docs/rules/space-unary-ops"
         },

package/lib/rules/spaced-comment.js

@@ -152,7 +152,6 @@ module.exports = {
 
         docs: {
             description: "enforce consistent spacing after the `//` or `/*` in a comment",
-            category: "Stylistic Issues",
             recommended: false,
             url: "https://eslint.org/docs/rules/spaced-comment"
         },

package/lib/rules/strict.js

@@ -69,7 +69,6 @@ module.exports = {
 
         docs: {
             description: "require or disallow strict mode directives",
-            category: "Strict Mode",
             recommended: false,
             url: "https://eslint.org/docs/rules/strict"
         },

package/lib/rules/switch-colon-spacing.js

@@ -21,7 +21,6 @@ module.exports = {
 
         docs: {
             description: "enforce spacing around colons of switch statements",
-            category: "Stylistic Issues",
             recommended: false,
             url: "https://eslint.org/docs/rules/switch-colon-spacing"
         },
@@ -51,18 +50,6 @@ module.exports = {
         const beforeSpacing = options.before === true; // false by default
         const afterSpacing = options.after !== false; // true by default
 
-        /**
-         * Get the colon token of the given SwitchCase node.
-         * @param {ASTNode} node The SwitchCase node to get.
-         * @returns {Token} The colon token of the node.
-         */
-        function getColonToken(node) {
-            if (node.test) {
-                return sourceCode.getTokenAfter(node.test, astUtils.isColonToken);
-            }
-            return sourceCode.getFirstToken(node, 1);
-        }
-
         /**
          * Check whether the spacing between the given 2 tokens is valid or not.
          * @param {Token} left The left token to check.
@@ -115,7 +102,7 @@ module.exports = {
 
         return {
             SwitchCase(node) {
-                const colonToken = getColonToken(node);
+                const colonToken = astUtils.getSwitchCaseColonToken(node, sourceCode);
                 const beforeToken = sourceCode.getTokenBefore(colonToken);
                 const afterToken = sourceCode.getTokenAfter(colonToken);
 

package/lib/rules/symbol-description.js

@@ -22,7 +22,6 @@ module.exports = {
 
         docs: {
             description: "require symbol descriptions",
-            category: "ECMAScript 6",
             recommended: false,
             url: "https://eslint.org/docs/rules/symbol-description"
         },

package/lib/rules/template-curly-spacing.js

@@ -21,7 +21,6 @@ module.exports = {
 
         docs: {
             description: "require or disallow spacing around embedded expressions of template strings",
-            category: "ECMAScript 6",
             recommended: false,
             url: "https://eslint.org/docs/rules/template-curly-spacing"
         },

package/lib/rules/template-tag-spacing.js

@@ -15,7 +15,6 @@ module.exports = {
 
         docs: {
             description: "require or disallow spacing between template tags and their literals",
-            category: "Stylistic Issues",
             recommended: false,
             url: "https://eslint.org/docs/rules/template-tag-spacing"
         },

package/lib/rules/unicode-bom.js

@@ -14,7 +14,6 @@ module.exports = {
 
         docs: {
             description: "require or disallow Unicode byte order mark (BOM)",
-            category: "Stylistic Issues",
             recommended: false,
             url: "https://eslint.org/docs/rules/unicode-bom"
         },

package/lib/rules/use-isnan.js

@@ -37,7 +37,6 @@ module.exports = {
 
         docs: {
             description: "require calls to `isNaN()` when checking for `NaN`",
-            category: "Possible Errors",
             recommended: true,
             url: "https://eslint.org/docs/rules/use-isnan"
         },

package/lib/rules/utils/ast-utils.js

@@ -756,6 +756,19 @@ function isLogicalAssignmentOperator(operator) {
     return LOGICAL_ASSIGNMENT_OPERATORS.has(operator);
 }
 
+/**
+ * Get the colon token of the given SwitchCase node.
+ * @param {ASTNode} node The SwitchCase node to get.
+ * @param {SourceCode} sourceCode The source code object to get tokens.
+ * @returns {Token} The colon token of the node.
+ */
+function getSwitchCaseColonToken(node, sourceCode) {
+    if (node.test) {
+        return sourceCode.getTokenAfter(node.test, isColonToken);
+    }
+    return sourceCode.getFirstToken(node, 1);
+}
+
 //------------------------------------------------------------------------------
 // Public Interface
 //------------------------------------------------------------------------------
@@ -858,8 +871,8 @@ module.exports = {
 
     /**
      * Validate that a string passed in is surrounded by the specified character
-     * @param  {string} val The text to check.
-     * @param  {string} character The character to see if it's surrounded by.
+     * @param {string} val The text to check.
+     * @param {string} character The character to see if it's surrounded by.
      * @returns {boolean} True if the text is surrounded by the character, false if not.
      * @private
      */
@@ -875,7 +888,14 @@ module.exports = {
     isDirectiveComment(node) {
         const comment = node.value.trim();
 
-        return /^(?:eslint[- ]|(?:globals?|exported) )/u.test(comment);
+        return (
+            node.type === "Line" && comment.indexOf("eslint-") === 0 ||
+            node.type === "Block" && (
+                comment.indexOf("global ") === 0 ||
+                comment.indexOf("eslint ") === 0 ||
+                comment.indexOf("eslint-") === 0
+            )
+        );
     },
 
     /**
@@ -1288,7 +1308,8 @@ module.exports = {
      * 5e1_000   // false
      * 5n        // false
      * 1_000n    // false
-     * '5'       // false
+     * "5"       // false
+     *
      */
     isDecimalInteger(node) {
         return node.type === "Literal" && typeof node.value === "number" &&
@@ -1632,9 +1653,9 @@ module.exports = {
         return sourceCode.getText().slice(leftToken.range[0], rightToken.range[1]);
     },
 
-    /*
+    /**
      * Determine if a node has a possibility to be an Error object
-     * @param  {ASTNode} node  ASTNode to check
+     * @param {ASTNode} node ASTNode to check
      * @returns {boolean} True if there is a chance it contains an Error obj
      */
     couldBeError(node) {
@@ -1864,5 +1885,6 @@ module.exports = {
     isSpecificMemberAccess,
     equalLiteralValue,
     isSameReference,
-    isLogicalAssignmentOperator
+    isLogicalAssignmentOperator,
+    getSwitchCaseColonToken
 };

package/lib/rules/utils/lazy-loading-rule-map.js

@@ -14,10 +14,10 @@ const debug = require("debug")("eslint:rules");
  * const rules = new LazyLoadingRuleMap([
  *     ["eqeqeq", () => require("eqeqeq")],
  *     ["semi", () => require("semi")],
- *     ["no-unused-vars", () => require("no-unused-vars")],
- * ])
+ *     ["no-unused-vars", () => require("no-unused-vars")]
+ * ]);
  *
- * rules.get("semi") // call `() => require("semi")` here.
+ * rules.get("semi"); // call `() => require("semi")` here.
  *
  * @extends {Map<string, () => Rule>}
  */

package/lib/rules/valid-jsdoc.js

@@ -1,6 +1,7 @@
 /**
  * @fileoverview Validates JSDoc comments are syntactically correct
  * @author Nicholas C. Zakas
+ * @deprecated in ESLint v5.10.0
  */
 "use strict";
 
@@ -20,7 +21,6 @@ module.exports = {
 
         docs: {
             description: "enforce valid JSDoc comments",
-            category: "Possible Errors",
             recommended: false,
             url: "https://eslint.org/docs/rules/valid-jsdoc"
         },

package/lib/rules/valid-typeof.js

@@ -14,7 +14,6 @@ module.exports = {
 
         docs: {
             description: "enforce comparing `typeof` expressions against valid strings",
-            category: "Possible Errors",
             recommended: true,
             url: "https://eslint.org/docs/rules/valid-typeof"
         },

package/lib/rules/vars-on-top.js

@@ -15,7 +15,6 @@ module.exports = {
 
         docs: {
             description: "require `var` declarations be placed at the top of their containing scope",
-            category: "Best Practices",
             recommended: false,
             url: "https://eslint.org/docs/rules/vars-on-top"
         },
@@ -32,8 +31,8 @@ module.exports = {
         // Helpers
         //--------------------------------------------------------------------------
 
-        // eslint-disable-next-line jsdoc/require-description
         /**
+         * Has AST suggesting a directive.
          * @param {ASTNode} node any node
          * @returns {boolean} whether the given node structurally represents a directive
          */

package/lib/rules/wrap-iife.js

@@ -43,7 +43,6 @@ module.exports = {
 
         docs: {
             description: "require parentheses around immediate `function` invocations",
-            category: "Best Practices",
             recommended: false,
             url: "https://eslint.org/docs/rules/wrap-iife"
         },

package/lib/rules/wrap-regex.js

@@ -15,7 +15,6 @@ module.exports = {
 
         docs: {
             description: "require parenthesis around regex literals",
-            category: "Stylistic Issues",
             recommended: false,
             url: "https://eslint.org/docs/rules/wrap-regex"
         },

package/lib/rules/yield-star-spacing.js

@@ -15,7 +15,6 @@ module.exports = {
 
         docs: {
             description: "require or disallow spacing around the `*` in `yield*` expressions",
-            category: "ECMAScript 6",
             recommended: false,
             url: "https://eslint.org/docs/rules/yield-star-spacing"
         },

package/lib/rules/yoda.js

@@ -121,7 +121,6 @@ module.exports = {
 
         docs: {
             description: 'require or disallow "Yoda" conditions',
-            category: "Best Practices",
             recommended: false,
             url: "https://eslint.org/docs/rules/yoda"
         },

package/lib/shared/ajv.js

@@ -27,7 +27,7 @@ module.exports = (additionalOptions = {}) => {
     });
 
     ajv.addMetaSchema(metaSchema);
-    // eslint-disable-next-line no-underscore-dangle
+    // eslint-disable-next-line no-underscore-dangle -- Ajv's API
     ajv._opts.defaultMeta = metaSchema.id;
 
     return ajv;

package/lib/shared/config-validator.js

@@ -84,6 +84,7 @@ function getRuleOptionsSchema(rule) {
 /**
  * Validates a rule's severity and returns the severity value. Throws an error if the severity is invalid.
  * @param {options} options The given options for the rule.
+ * @throws {Error} Wrong severity value.
  * @returns {number|string} The rule's severity value
  */
 function validateRuleSeverity(options) {
@@ -102,6 +103,7 @@ function validateRuleSeverity(options) {
  * Validates the non-severity options passed to a rule, based on its schema.
  * @param {{create: Function}} rule The rule to validate
  * @param {Array} localOptions The options for the rule, excluding severity
+ * @throws {Error} Any rule validation errors.
  * @returns {void}
  */
 function validateRuleSchema(rule, localOptions) {
@@ -132,6 +134,7 @@ function validateRuleSchema(rule, localOptions) {
  * @param {Array|number} options The given options for the rule.
  * @param {string|null} source The name of the configuration source to report in any errors. If null or undefined,
  * no source is prepended to the message.
+ * @throws {Error} Upon any bad rule configuration.
  * @returns {void}
  */
 function validateRuleOptions(rule, ruleId, options, source = null) {
@@ -156,7 +159,7 @@ function validateRuleOptions(rule, ruleId, options, source = null) {
  * Validates an environment object
  * @param {Object} environment The environment config object to validate.
  * @param {string} source The name of the configuration source to report in any errors.
- * @param {function(envId:string): Object} [getAdditionalEnv] A map from strings to loaded environments.
+ * @param {(envId:string) => Object} [getAdditionalEnv] A map from strings to loaded environments.
  * @returns {void}
  */
 function validateEnvironment(
@@ -185,7 +188,7 @@ function validateEnvironment(
  * Validates a rules config object
  * @param {Object} rulesConfig The rules config object to validate.
  * @param {string} source The name of the configuration source to report in any errors.
- * @param {function(ruleId:string): Object} getAdditionalRule A map from strings to loaded rules
+ * @param {(ruleId:string) => Object} getAdditionalRule A map from strings to loaded rules
  * @returns {void}
  */
 function validateRules(
@@ -229,7 +232,8 @@ function validateGlobals(globalsConfig, source = null) {
  * Validate `processor` configuration.
  * @param {string|undefined} processorName The processor name.
  * @param {string} source The name of config file.
- * @param {function(id:string): Processor} getProcessor The getter of defined processors.
+ * @param {(id:string) => Processor} getProcessor The getter of defined processors.
+ * @throws {Error} For invalid processor configuration.
  * @returns {void}
  */
 function validateProcessor(processorName, source, getProcessor) {
@@ -268,6 +272,7 @@ function formatErrors(errors) {
  * Validates the top level properties of the config object.
  * @param {Object} config The config object to validate.
  * @param {string} source The name of the configuration source to report in any errors.
+ * @throws {Error} For any config invalid per the schema.
  * @returns {void}
  */
 function validateConfigSchema(config, source = null) {
@@ -286,8 +291,8 @@ function validateConfigSchema(config, source = null) {
  * Validates an entire config object.
  * @param {Object} config The config object to validate.
  * @param {string} source The name of the configuration source to report in any errors.
- * @param {function(ruleId:string): Object} [getAdditionalRule] A map from strings to loaded rules.
- * @param {function(envId:string): Object} [getAdditionalEnv] A map from strings to loaded envs.
+ * @param {(ruleId:string) => Object} [getAdditionalRule] A map from strings to loaded rules.
+ * @param {(envId:string) => Object} [getAdditionalEnv] A map from strings to loaded envs.
  * @returns {void}
  */
 function validate(config, source, getAdditionalRule, getAdditionalEnv) {

package/lib/shared/logging.js

@@ -5,7 +5,7 @@
 
 "use strict";
 
-/* eslint no-console: "off" */
+/* eslint no-console: "off" -- Logging util */
 
 /* istanbul ignore next */
 module.exports = {

package/lib/shared/relative-module-resolver.js

@@ -26,6 +26,7 @@ module.exports = {
      * @param {string} moduleName The name of a Node module, or a path to a Node module.
      * @param {string} relativeToPath An absolute path indicating the module that `moduleName` should be resolved relative to. This must be
      * a file rather than a directory, but the file need not actually exist.
+     * @throws {Error} Any error from `module.createRequire` or its `resolve`.
      * @returns {string} The absolute path that would result from calling `require.resolve(moduleName)` in a file located at `relativeToPath`
      */
     resolve(moduleName, relativeToPath) {

package/lib/shared/runtime-info.js

@@ -40,6 +40,7 @@ function environment() {
      * Synchronously executes a shell command and formats the result.
      * @param {string} cmd The command to execute.
      * @param {Array} args The arguments to be executed with the command.
+     * @throws {Error} As may be collected by `cross-spawn.sync`.
      * @returns {string} The version returned by the command.
      */
     function execCommand(cmd, args) {
@@ -73,6 +74,7 @@ function environment() {
     /**
      * Gets bin version.
      * @param {string} bin The bin to check.
+     * @throws {Error} As may be collected by `cross-spawn.sync`.
      * @returns {string} The normalized version returned by the command.
      */
     function getBinVersion(bin) {
@@ -90,6 +92,7 @@ function environment() {
      * Gets installed npm package version.
      * @param {string} pkg The package to check.
      * @param {boolean} global Whether to check globally or not.
+     * @throws {Error} As may be collected by `cross-spawn.sync`.
      * @returns {string} The normalized version returned by the command.
      */
     function getNpmPackageVersion(pkg, { global = false } = {}) {

package/lib/shared/traverser.js

@@ -65,16 +65,16 @@ class Traverser {
         this._leave = null;
     }
 
-    // eslint-disable-next-line jsdoc/require-description
     /**
+     * Gives current node.
      * @returns {ASTNode} The current node.
      */
     current() {
         return this._current;
     }
 
-    // eslint-disable-next-line jsdoc/require-description
     /**
+     * Gives a a copy of the ancestor nodes.
      * @returns {ASTNode[]} The ancestor nodes.
      */
     parents() {

package/lib/shared/types.js

@@ -83,12 +83,12 @@ module.exports = {};
 
 /**
  * @typedef {Object} LintMessage
- * @property {number} column The 1-based column number.
+ * @property {number|undefined} column The 1-based column number.
  * @property {number} [endColumn] The 1-based column number of the end location.
  * @property {number} [endLine] The 1-based line number of the end location.
  * @property {boolean} fatal If `true` then this is a fatal error.
  * @property {{range:[number,number], text:string}} [fix] Information for autofix.
- * @property {number} line The 1-based line number.
+ * @property {number|undefined} line The 1-based line number.
  * @property {string} message The error message.
  * @property {string|null} ruleId The ID of the rule which makes this message.
  * @property {0|1|2} severity The severity of this message.

package/lib/source-code/source-code.js

@@ -143,10 +143,12 @@ function isSpaceBetween(sourceCode, first, second, checkInsideOfJSXText) {
 // Public Interface
 //------------------------------------------------------------------------------
 
+/**
+ * Represents parsed source code.
+ */
 class SourceCode extends TokenStore {
 
     /**
-     * Represents parsed source code.
      * @param {string|Object} textOrConfig The source code text or config object.
      * @param {string} textOrConfig.text The source code text.
      * @param {ASTNode} textOrConfig.ast The Program node of the AST representing the code. This AST should be created from the text that BOM was stripped.
@@ -175,20 +177,20 @@ class SourceCode extends TokenStore {
 
         /**
          * The flag to indicate that the source code has Unicode BOM.
-         * @type boolean
+         * @type {boolean}
          */
         this.hasBOM = (text.charCodeAt(0) === 0xFEFF);
 
         /**
          * The original text source code.
          * BOM was stripped from this text.
-         * @type string
+         * @type {string}
          */
         this.text = (this.hasBOM ? text.slice(1) : text);
 
         /**
          * The parsed AST for the source code.
-         * @type ASTNode
+         * @type {ASTNode}
          */
         this.ast = ast;
 
@@ -223,7 +225,7 @@ class SourceCode extends TokenStore {
         /**
          * The source code split into lines according to ECMA-262 specification.
          * This is done to avoid each rule needing to do so separately.
-         * @type string[]
+         * @type {string[]}
          */
         this.lines = [];
         this.lineStartIndices = [0];
@@ -506,6 +508,7 @@ class SourceCode extends TokenStore {
     /**
      * Converts a source text index into a (line, column) pair.
      * @param {number} index The index of a character in a file
+     * @throws {TypeError} If non-numeric index or index out of range.
      * @returns {Object} A {line, column} location object with a 0-indexed column
      * @public
      */
@@ -545,6 +548,9 @@ class SourceCode extends TokenStore {
      * @param {Object} loc A line/column location
      * @param {number} loc.line The line number of the location (1-indexed)
      * @param {number} loc.column The column number of the location (0-indexed)
+     * @throws {TypeError|RangeError} If `loc` is not an object with a numeric
+     *   `line` and `column`, if the `line` is less than or equal to zero or
+     *   the line or column is out of the expected range.
      * @returns {number} The range index of the location in the file.
      * @public
      */

package/lib/source-code/token-store/cursor.js

@@ -70,7 +70,7 @@ module.exports = class Cursor {
      * @abstract
      */
     /* istanbul ignore next */
-    moveNext() { // eslint-disable-line class-methods-use-this
+    moveNext() { // eslint-disable-line class-methods-use-this -- Unused
         throw new Error("Not implemented.");
     }
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eslint",
-  "version": "8.0.0-beta.0",
+  "version": "8.0.0",
   "author": "Nicholas C. Zakas <nicholas+npm@nczconsulting.com>",
   "description": "An AST-based pattern checker for JavaScript.",
   "bin": {
@@ -23,7 +23,6 @@
     "generate-betarelease": "node Makefile.js generatePrerelease -- beta",
     "generate-rcrelease": "node Makefile.js generatePrerelease -- rc",
     "publish-release": "node Makefile.js publishRelease",
-    "docs": "node Makefile.js docs",
     "gensite": "node Makefile.js gensite",
     "webpack": "node Makefile.js webpack",
     "perf": "node Makefile.js perf"
@@ -48,7 +47,7 @@
   "homepage": "https://eslint.org",
   "bugs": "https://github.com/eslint/eslint/issues/",
   "dependencies": {
-    "@eslint/eslintrc": "^1.0.0",
+    "@eslint/eslintrc": "^1.0.2",
     "@humanwhocodes/config-array": "^0.6.0",
     "ajv": "^6.10.0",
     "chalk": "^4.0.0",
@@ -60,7 +59,7 @@
     "eslint-scope": "^6.0.0",
     "eslint-utils": "^3.0.0",
     "eslint-visitor-keys": "^3.0.0",
-    "espree": "^8.0.0",
+    "espree": "^9.0.0",
     "esquery": "^1.4.0",
     "esutils": "^2.0.2",
     "fast-deep-equal": "^3.1.3",
@@ -99,9 +98,10 @@
     "ejs": "^3.0.2",
     "eslint": "file:.",
     "eslint-config-eslint": "file:packages/eslint-config-eslint",
+    "eslint-plugin-eslint-comments": "^3.2.0",
     "eslint-plugin-eslint-plugin": "^3.5.3",
     "eslint-plugin-internal-rules": "file:tools/internal-rules",
-    "eslint-plugin-jsdoc": "^33.3.0",
+    "eslint-plugin-jsdoc": "^36.0.6",
     "eslint-plugin-node": "^11.1.0",
     "eslint-release": "^3.1.2",
     "eslump": "^3.0.0",