eslint 4.12.1 → 4.15.0

package/CHANGELOG.md

@@ -1,3 +1,52 @@
+v4.15.0 - January 6, 2018
+
+* 6ab04b5 New: Add context.report({ messageId }) (fixes #6740) (#9165) (Jed Fox)
+* fc7f404 Docs: add url to each of the rules (refs #6582) (#9788) (Patrick McElhaney)
+* fc44da9 Docs: fix sort-imports rule block language (#9805) (ferhat elmas)
+* 65f0176 New: CLIEngine#getRules() (refs #6582) (#9782) (Patrick McElhaney)
+* c64195f Update: More detailed assert message for rule-tester (#9769) (Weijia Wang)
+* 9fcfabf Fix: no-extra-parens false positive (fixes: #9755) (#9795) (Erin)
+* 61e5fa0 Docs: Add table of contents to Node.js API docs (#9785) (Patrick McElhaney)
+* 4c87f42 Fix: incorrect error messages of no-unused-vars (fixes #9774) (#9791) (akouryy)
+* bbabf34 Update: add `ignoreComments` option to `indent` rule (fixes #9018) (#9752) (Kevin Partington)
+* db431cb Docs: HTTP -> HTTPS (fixes #9768) (#9768) (Ronald Eddy Jr)
+* cbf0fb9 Docs: describe how to feature-detect scopeManager/visitorKeys support (#9764) (Teddy Katz)
+* f7dcb70 Docs: Add note about "patch release pending" label to maintainer guide (#9763) (Teddy Katz)
+
+v4.14.0 - December 23, 2017
+
+* be2f57e Update: support separate requires in one-var. (fixes #6175) (#9441) (薛定谔的猫)
+* 370d614 Docs: Fix typos (#9751) (Jed Fox)
+* 8196c45 Chore: Reorganize CLI options and associated docs (#9758) (Kevin Partington)
+* 75c7419 Update: Logical-and is counted in `complexity` rule (fixes #8535) (#9754) (Kevin Partington)
+* eb4b1e0 Docs: reintroduce misspelling in `valid-typeof` example (#9753) (Teddy Katz)
+* ae51eb2 New: Add allowImplicit option to array-callback-return (fixes #8539) (#9344) (James C. Davis)
+* e9d5dfd Docs: improve no-extra-parens formatting (#9747) (Rich Trott)
+* 37d066c Chore: Add unit tests for overrides glob matching. (#9744) (Robert Jackson)
+* 805a94e Chore: Fix typo in CLIEngine test name (#9741) (@scriptdaemon)
+* 1c2aafd Update: Improve parser integrations (fixes #8392) (#8755) (Toru Nagashima)
+* 4ddc131 Upgrade: debug@^3.1.0 (#9731) (Kevin Partington)
+* f252c19 Docs: Make the lint message `source` property a little more subtle (#9735) (Jed Fox)
+* 5a5c23c Docs: fix the link to contributing page (#9727) (Victor Hom)
+* f44ce11 Docs: change beginner to good first issue label text (#9726) (Victor Hom)
+* 14baa2e Chore: improve arrow-body-style error message (refs #5498) (#9718) (Teddy Katz)
+* f819920 Docs: fix typos (#9723) (Thomas Broadley)
+* 43d4ba8 Fix: false positive on rule`lines-between-class-members` (fixes #9665) (#9680) (sakabar)
+
+v4.13.1 - December 11, 2017
+
+* b72dc83 Fix: eol-last allow empty-string to always pass (refs #9534) (#9696) (Kevin Partington)
+* d80aa7c Fix: camelcase destructure leading/trailing underscore (fixes #9700) (#9701) (Kevin Partington)
+* d49d9d0 Docs: Add missing period to the README (#9702) (Kevin Partington)
+* 4564fe0 Chore: no-invalid-meta crash if no export assignment (refs #9534) (#9698) (Kevin Partington)
+
+v4.13.0 - December 8, 2017
+
+* 256481b Update: update handling of destructuring in camelcase (fixes #8511) (#9468) (Erin)
+* d067ae1 Docs: Don’t use undocumented array-style configuration for max-len (#9690) (Jed Fox)
+* 1ad3091 Chore: fix test-suite to work with node master (#9688) (Myles Borins)
+* cdb1488 Docs: Adds an example with try/catch. (#9672) (Jaap Taal)
+
 v4.12.1 - November 30, 2017
 
 * 1e362a0 Revert "Fix: Use XML 1.1 on XML formatters (fixes #9607) (#9608)" (#9667) (Kevin Partington)

package/README.md

@@ -156,7 +156,7 @@ Before filing an issue, please be sure to read the guidelines for what you're re
 
 ## Semantic Versioning Policy
 
-ESLint follows [semantic versioning](http://semver.org). However, due to the nature of ESLint as a code quality tool, it's not always clear when a minor or major version bump occurs. To help clarify this for everyone, we've defined the following semantic versioning policy for ESLint:
+ESLint follows [semantic versioning](https://semver.org). However, due to the nature of ESLint as a code quality tool, it's not always clear when a minor or major version bump occurs. To help clarify this for everyone, we've defined the following semantic versioning policy for ESLint:
 
 * Patch release (intended to not break your lint build)
     * A bug fix in a rule that results in ESLint reporting fewer errors.
@@ -188,7 +188,7 @@ According to our policy, any minor update may report more errors than the previo
 
 ### How is ESLint different from JSHint?
 
-The most significant difference is that ESlint has pluggable linting rules. That means you can use the rules it comes with, or you can extend it with rules created by others or by yourself!
+The most significant difference is that ESLint has pluggable linting rules. That means you can use the rules it comes with, or you can extend it with rules created by others or by yourself!
 
 ### How does ESLint performance compare to JSHint?
 
@@ -239,7 +239,7 @@ Once a language feature has been adopted into the ECMAScript standard (stage 4 a
 
 ### Where to ask for help?
 
-Join our [Mailing List](https://groups.google.com/group/eslint) or [Chatroom](https://gitter.im/eslint/eslint)
+Join our [Mailing List](https://groups.google.com/group/eslint) or [Chatroom](https://gitter.im/eslint/eslint).
 
 
 [npm-image]: https://img.shields.io/npm/v/eslint.svg?style=flat-square

package/lib/cli-engine.js

@@ -420,6 +420,10 @@ class CLIEngine {
         this.config = new Config(this.options, this.linter);
     }
 
+    getRules() {
+        return this.linter.getRules();
+    }
+
     /**
      * Returns results that only contains errors.
      * @param {LintResult[]} results The results to filter.

package/lib/linter.js

@@ -10,6 +10,7 @@
 //------------------------------------------------------------------------------
 
 const eslintScope = require("eslint-scope"),
+    evk = require("eslint-visitor-keys"),
     levn = require("levn"),
     lodash = require("lodash"),
     blankScriptAST = require("../conf/blank-script.json"),
@@ -43,6 +44,8 @@ const MAX_AUTOFIX_PASSES = 10;
  * @property {ASTNode} ast The ESTree AST Program node.
  * @property {Object} services An object containing additional services related
  *      to the parser.
+ * @property {ScopeManager|null} scopeManager The scope manager object of this AST.
+ * @property {Object|null} visitorKeys The visitor keys to traverse this AST.
  */
 
 //------------------------------------------------------------------------------
@@ -501,6 +504,28 @@ function getRuleOptions(ruleConfig) {
 
 }
 
+/**
+ * Analyze scope of the given AST.
+ * @param {ASTNode} ast The `Program` node to analyze.
+ * @param {Object} parserOptions The parser options.
+ * @param {Object} visitorKeys The visitor keys.
+ * @returns {ScopeManager} The analysis result.
+ */
+function analyzeScope(ast, parserOptions, visitorKeys) {
+    const ecmaFeatures = parserOptions.ecmaFeatures || {};
+    const ecmaVersion = parserOptions.ecmaVersion || 5;
+
+    return eslintScope.analyze(ast, {
+        ignoreEval: true,
+        nodejsScope: ecmaFeatures.globalReturn,
+        impliedStrict: ecmaFeatures.impliedStrict,
+        ecmaVersion,
+        sourceType: parserOptions.sourceType || "script",
+        childVisitorKeys: visitorKeys || evk.KEYS,
+        fallback: Traverser.getKeys
+    });
+}
+
 /**
  * Parses text into an AST. Moved out here because the try-catch prevents
  * optimization of functions, so it's best to keep the try-catch as isolated
@@ -509,18 +534,20 @@ function getRuleOptions(ruleConfig) {
  * @param {Object} providedParserOptions Options to pass to the parser
  * @param {Object} parser The parser module
  * @param {string} filePath The path to the file being parsed.
- * @returns {{success: false, error: Problem}|{success: true,ast: ASTNode, services: Object}}
+ * @returns {{success: false, error: Problem}|{success: true, sourceCode: SourceCode}}
  * An object containing the AST and parser services if parsing was successful, or the error if parsing failed
  * @private
  */
 function parse(text, providedParserOptions, parser, filePath) {
-
+    const textToParse = stripUnicodeBOM(text).replace(astUtils.SHEBANG_MATCHER, (match, captured) => `//${captured}`);
     const parserOptions = Object.assign({}, providedParserOptions, {
         loc: true,
         range: true,
         raw: true,
         tokens: true,
         comment: true,
+        eslintVisitorKeys: true,
+        eslintScopeManager: true,
         filePath
     });
 
@@ -531,20 +558,30 @@ function parse(text, providedParserOptions, parser, filePath) {
      * problem that ESLint identified just like any other.
      */
     try {
-        if (typeof parser.parseForESLint === "function") {
-            const parseResult = parser.parseForESLint(text, parserOptions);
-
-            return {
-                success: true,
-                ast: parseResult.ast,
-                services: parseResult.services || {}
-            };
-        }
+        const parseResult = (typeof parser.parseForESLint === "function")
+            ? parser.parseForESLint(textToParse, parserOptions)
+            : { ast: parser.parse(textToParse, parserOptions) };
+        const ast = parseResult.ast;
+        const parserServices = parseResult.services || {};
+        const visitorKeys = parseResult.visitorKeys || evk.KEYS;
+        const scopeManager = parseResult.scopeManager || analyzeScope(ast, parserOptions, visitorKeys);
 
         return {
             success: true,
-            ast: parser.parse(text, parserOptions),
-            services: {}
+
+            /*
+             * Save all values that `parseForESLint()` returned.
+             * If a `SourceCode` object is given as the first parameter instead of source code text,
+             * linter skips the parsing process and reuses the source code object.
+             * In that case, linter needs all the values that `parseForESLint()` returned.
+             */
+            sourceCode: new SourceCode({
+                text,
+                ast,
+                parserServices,
+                scopeManager,
+                visitorKeys
+            })
         };
     } catch (ex) {
 
@@ -717,7 +754,6 @@ module.exports = class Linter {
      */
     _verifyWithoutProcessors(textOrSourceCode, config, filenameOrOptions) {
         let text,
-            parserServices,
             allowInlineConfig,
             providedFilename,
             reportUnusedDisableDirectives;
@@ -731,8 +767,6 @@ module.exports = class Linter {
             providedFilename = filenameOrOptions;
         }
 
-        const filename = typeof providedFilename === "string" ? providedFilename : "<input>";
-
         if (typeof textOrSourceCode === "string") {
             lastSourceCodes.set(this, null);
             text = textOrSourceCode;
@@ -741,6 +775,8 @@ module.exports = class Linter {
             text = textOrSourceCode.text;
         }
 
+        const filename = typeof providedFilename === "string" ? providedFilename : "<input>";
+
         // search and apply "eslint-env *".
         const envInFile = findEslintEnv(text);
 
@@ -757,9 +793,7 @@ module.exports = class Linter {
         // process initial config to make it safe to extend
         config = prepareConfig(config, this.environments);
 
-        if (lastSourceCodes.get(this)) {
-            parserServices = {};
-        } else {
+        if (!lastSourceCodes.get(this)) {
 
             // there's no input, just exit here
             if (text.trim().length === 0) {
@@ -783,7 +817,7 @@ module.exports = class Linter {
                 }];
             }
             const parseResult = parse(
-                stripUnicodeBOM(text).replace(astUtils.SHEBANG_MATCHER, (match, captured) => `//${captured}`),
+                text,
                 config.parserOptions,
                 parser,
                 filename
@@ -793,8 +827,24 @@ module.exports = class Linter {
                 return [parseResult.error];
             }
 
-            parserServices = parseResult.services;
-            lastSourceCodes.set(this, new SourceCode(text, parseResult.ast));
+            lastSourceCodes.set(this, parseResult.sourceCode);
+        } else {
+
+            /*
+             * If the given source code object as the first argument does not have scopeManager, analyze the scope.
+             * This is for backward compatibility (SourceCode is frozen so it cannot rebind).
+             */
+            const lastSourceCode = lastSourceCodes.get(this);
+
+            if (!lastSourceCode.scopeManager) {
+                lastSourceCodes.set(this, new SourceCode({
+                    text: lastSourceCode.text,
+                    ast: lastSourceCode.ast,
+                    parserServices: lastSourceCode.parserServices,
+                    visitorKeys: lastSourceCode.visitorKeys,
+                    scopeManager: analyzeScope(lastSourceCode.ast, config.parserOptions)
+                }));
+            }
         }
 
         const problems = [];
@@ -814,16 +864,7 @@ module.exports = class Linter {
 
         const emitter = createEmitter();
         const traverser = new Traverser();
-        const ecmaFeatures = config.parserOptions.ecmaFeatures || {};
-        const ecmaVersion = config.parserOptions.ecmaVersion || 5;
-        const scopeManager = eslintScope.analyze(sourceCode.ast, {
-            ignoreEval: true,
-            nodejsScope: ecmaFeatures.globalReturn,
-            impliedStrict: ecmaFeatures.impliedStrict,
-            ecmaVersion,
-            sourceType: config.parserOptions.sourceType || "script",
-            fallback: Traverser.getKeys
-        });
+        const scopeManager = sourceCode.scopeManager;
 
         /*
          * Create a frozen object with the ruleContext properties and methods that are shared by all rules.
@@ -842,7 +883,7 @@ module.exports = class Linter {
                     markVariableAsUsed: name => markVariableAsUsed(scopeManager, traverser.current(), config.parserOptions, name),
                     parserOptions: config.parserOptions,
                     parserPath: config.parser,
-                    parserServices,
+                    parserServices: sourceCode.parserServices,
                     settings: config.settings,
 
                     /**
@@ -870,6 +911,7 @@ module.exports = class Linter {
             }
 
             const rule = this.rules.get(ruleId);
+            const messageIds = rule && rule.meta && rule.meta.messages;
             let reportTranslator = null;
             const ruleContext = Object.freeze(
                 Object.assign(
@@ -890,7 +932,7 @@ module.exports = class Linter {
                              * with Node 8.4.0.
                              */
                             if (reportTranslator === null) {
-                                reportTranslator = createReportTranslator({ ruleId, severity, sourceCode });
+                                reportTranslator = createReportTranslator({ ruleId, severity, sourceCode, messageIds });
                             }
                             const problem = reportTranslator.apply(null, arguments);
 
@@ -957,7 +999,8 @@ module.exports = class Linter {
             },
             leave(node) {
                 eventGenerator.leaveNode(node);
-            }
+            },
+            visitorKeys: sourceCode.visitorKeys
         });
 
         return applyDisableDirectives({

package/lib/options.js

@@ -64,26 +64,6 @@ module.exports = optionator({
             type: "Object",
             description: "Specify parser options"
         },
-        {
-            heading: "Caching"
-        },
-        {
-            option: "cache",
-            type: "Boolean",
-            default: "false",
-            description: "Only check changed files"
-        },
-        {
-            option: "cache-file",
-            type: "path::String",
-            default: ".eslintcache",
-            description: "Path to the cache file. Deprecated: use --cache-location"
-        },
-        {
-            option: "cache-location",
-            type: "path::String",
-            description: "Path to the cache file or directory"
-        },
         {
             heading: "Specifying rules and plugins"
         },
@@ -102,6 +82,21 @@ module.exports = optionator({
             type: "Object",
             description: "Specify rules"
         },
+        {
+            heading: "Fixing problems"
+        },
+        {
+            option: "fix",
+            type: "Boolean",
+            default: false,
+            description: "Automatically fix problems"
+        },
+        {
+            option: "fix-dry-run",
+            type: "Boolean",
+            default: false,
+            description: "Automatically fix problems without saving the changes to the file system"
+        },
         {
             heading: "Ignoring files"
         },
@@ -176,25 +171,48 @@ module.exports = optionator({
             description: "Force enabling/disabling of color"
         },
         {
-            heading: "Miscellaneous"
+            heading: "Inline configuration comments"
         },
         {
-            option: "init",
+            option: "inline-config",
             type: "Boolean",
-            default: "false",
-            description: "Run config initialization wizard"
+            default: "true",
+            description: "Prevent comments from changing config or rules"
         },
         {
-            option: "fix",
+            option: "report-unused-disable-directives",
             type: "Boolean",
             default: false,
-            description: "Automatically fix problems"
+            description: "Adds reported errors for unused eslint-disable directives"
         },
         {
-            option: "fix-dry-run",
+            heading: "Caching"
+        },
+        {
+            option: "cache",
             type: "Boolean",
-            default: false,
-            description: "Automatically fix problems without saving the changes to the file system"
+            default: "false",
+            description: "Only check changed files"
+        },
+        {
+            option: "cache-file",
+            type: "path::String",
+            default: ".eslintcache",
+            description: "Path to the cache file. Deprecated: use --cache-location"
+        },
+        {
+            option: "cache-location",
+            type: "path::String",
+            description: "Path to the cache file or directory"
+        },
+        {
+            heading: "Miscellaneous"
+        },
+        {
+            option: "init",
+            type: "Boolean",
+            default: "false",
+            description: "Run config initialization wizard"
         },
         {
             option: "debug",
@@ -214,18 +232,6 @@ module.exports = optionator({
             type: "Boolean",
             description: "Output the version number"
         },
-        {
-            option: "inline-config",
-            type: "Boolean",
-            default: "true",
-            description: "Prevent comments from changing config or rules"
-        },
-        {
-            option: "report-unused-disable-directives",
-            type: "Boolean",
-            default: false,
-            description: "Adds reported errors for unused eslint-disable directives"
-        },
         {
             option: "print-config",
             type: "path::String",

package/lib/report-translator.js

@@ -11,6 +11,7 @@
 
 const assert = require("assert");
 const ruleFixer = require("./util/rule-fixer");
+const interpolate = require("./util/interpolate");
 
 //------------------------------------------------------------------------------
 // Typedefs
@@ -41,7 +42,9 @@ function normalizeMultiArgReportCall() {
 
     // If there is one argument, it is considered to be a new-style call already.
     if (arguments.length === 1) {
-        return arguments[0];
+
+        // Shallow clone the object to avoid surprises if reusing the descriptor
+        return Object.assign({}, arguments[0]);
     }
 
     // If the second argument is a string, the arguments are interpreted as [node, message, data, fix].
@@ -100,16 +103,7 @@ function normalizeReportLoc(descriptor) {
  * @returns {string} The interpolated message for the descriptor
  */
 function normalizeMessagePlaceholders(descriptor) {
-    if (!descriptor.data) {
-        return descriptor.message;
-    }
-    return descriptor.message.replace(/\{\{\s*([^{}]+?)\s*\}\}/g, (fullMatch, term) => {
-        if (term in descriptor.data) {
-            return descriptor.data[term];
-        }
-
-        return fullMatch;
-    });
+    return interpolate(descriptor.message, descriptor.data);
 }
 
 /**
@@ -216,6 +210,14 @@ function createProblem(options) {
         source: options.sourceLines[options.loc.start.line - 1] || ""
     };
 
+    /*
+     * If this isn’t in the conditional, some of the tests fail
+     * because `messageId` is present in the problem object
+     */
+    if (options.messageId) {
+        problem.messageId = options.messageId;
+    }
+
     if (options.loc.end) {
         problem.endLine = options.loc.end.line;
         problem.endColumn = options.loc.end.column + 1;
@@ -231,12 +233,13 @@ function createProblem(options) {
 /**
  * Returns a function that converts the arguments of a `context.report` call from a rule into a reported
  * problem for the Node.js API.
- * @param {{ruleId: string, severity: number, sourceCode: SourceCode}} metadata Metadata for the reported problem
+ * @param {{ruleId: string, severity: number, sourceCode: SourceCode, messageIds: Object}} metadata Metadata for the reported problem
  * @param {SourceCode} sourceCode The `SourceCode` instance for the text being linted
  * @returns {function(...args): {
  *      ruleId: string,
  *      severity: (0|1|2),
- *      message: string,
+ *      message: (string|undefined),
+ *      messageId: (string|undefined),
  *      line: number,
  *      column: number,
  *      endLine: (number|undefined),
@@ -261,11 +264,29 @@ module.exports = function createReportTranslator(metadata) {
 
         assertValidNodeInfo(descriptor);
 
+        if (descriptor.messageId) {
+            if (!metadata.messageIds) {
+                throw new TypeError("context.report() called with a messageId, but no messages were present in the rule metadata.");
+            }
+            const id = descriptor.messageId;
+            const messages = metadata.messageIds;
+
+            if (descriptor.message) {
+                throw new TypeError("context.report() called with a message and a messageId. Please only pass one.");
+            }
+            if (!messages || !Object.prototype.hasOwnProperty.call(messages, id)) {
+                throw new TypeError(`context.report() called with a messageId of '${id}' which is not present in the 'messages' config: ${JSON.stringify(messages, null, 2)}`);
+            }
+            descriptor.message = messages[id];
+        }
+
+
         return createProblem({
             ruleId: metadata.ruleId,
             severity: metadata.severity,
             node: descriptor.node,
             message: normalizeMessagePlaceholders(descriptor),
+            messageId: descriptor.messageId,
             loc: normalizeReportLoc(descriptor),
             fix: normalizeFixes(descriptor, metadata.sourceCode),
             sourceLines: metadata.sourceCode.lines

package/lib/rules/.eslintrc.yml

@@ -1,3 +1,4 @@
 rules:
     rulesdir/no-invalid-meta: "error"
     rulesdir/consistent-docs-description: "error"
+    rulesdir/consistent-docs-url: "error"

package/lib/rules/accessor-pairs.js

@@ -75,7 +75,8 @@ module.exports = {
         docs: {
             description: "enforce getter and setter pairs in objects",
             category: "Best Practices",
-            recommended: false
+            recommended: false,
+            url: "https://eslint.org/docs/rules/accessor-pairs"
         },
         schema: [{
             type: "object",

package/lib/rules/array-bracket-newline.js

@@ -16,7 +16,8 @@ module.exports = {
         docs: {
             description: "enforce linebreaks after opening and before closing array brackets",
             category: "Stylistic Issues",
-            recommended: false
+            recommended: false,
+            url: "https://eslint.org/docs/rules/array-bracket-newline"
         },
         fixable: "whitespace",
         schema: [

package/lib/rules/array-bracket-spacing.js

@@ -15,7 +15,8 @@ module.exports = {
         docs: {
             description: "enforce consistent spacing inside array brackets",
             category: "Stylistic Issues",
-            recommended: false
+            recommended: false,
+            url: "https://eslint.org/docs/rules/array-bracket-spacing"
         },
         fixable: "whitespace",
         schema: [

package/lib/rules/array-callback-return.js

@@ -142,13 +142,27 @@ module.exports = {
         docs: {
             description: "enforce `return` statements in callbacks of array methods",
             category: "Best Practices",
-            recommended: false
+            recommended: false,
+            url: "https://eslint.org/docs/rules/array-callback-return"
         },
 
-        schema: []
+        schema: [
+            {
+                type: "object",
+                properties: {
+                    allowImplicit: {
+                        type: "boolean"
+                    }
+                },
+                additionalProperties: false
+            }
+        ]
     },
 
     create(context) {
+
+        const options = context.options[0] || { allowImplicit: false };
+
         let funcInfo = {
             upper: null,
             codePath: null,
@@ -212,7 +226,8 @@ module.exports = {
                 if (funcInfo.shouldCheck) {
                     funcInfo.hasReturn = true;
 
-                    if (!node.argument) {
+                    // if allowImplicit: false, should also check node.argument
+                    if (!options.allowImplicit && !node.argument) {
                         context.report({
                             node,
                             message: "{{name}} expected a return value.",

package/lib/rules/array-element-newline.js

@@ -16,7 +16,8 @@ module.exports = {
         docs: {
             description: "enforce line breaks after each array element",
             category: "Stylistic Issues",
-            recommended: false
+            recommended: false,
+            url: "https://eslint.org/docs/rules/array-element-newline"
         },
         fixable: "whitespace",
         schema: [

package/lib/rules/arrow-body-style.js

@@ -19,7 +19,8 @@ module.exports = {
         docs: {
             description: "require braces around arrow function bodies",
             category: "ECMAScript 6",
-            recommended: false
+            recommended: false,
+            url: "https://eslint.org/docs/rules/arrow-body-style"
         },
 
         schema: {
@@ -109,10 +110,22 @@ module.exports = {
                 }
 
                 if (never || asNeeded && blockBody[0].type === "ReturnStatement") {
+                    let message;
+
+                    if (blockBody.length === 0) {
+                        message = "Unexpected block statement surrounding arrow body; put a value of `undefined` immediately after the `=>`.";
+                    } else if (blockBody.length > 1) {
+                        message = "Unexpected block statement surrounding arrow body.";
+                    } else if (astUtils.isOpeningBraceToken(sourceCode.getFirstToken(blockBody[0], { skip: 1 }))) {
+                        message = "Unexpected block statement surrounding arrow body; parenthesize the returned value and move it immediately after the `=>`.";
+                    } else {
+                        message = "Unexpected block statement surrounding arrow body; move the returned value immediately after the `=>`.";
+                    }
+
                     context.report({
                         node,
                         loc: arrowBody.loc.start,
-                        message: "Unexpected block statement surrounding arrow body.",
+                        message,
                         fix(fixer) {
                             const fixes = [];