eslint 6.5.0 → 6.7.1

package/lib/linter/code-path-analysis/fork-context.js

@@ -22,8 +22,7 @@ const assert = require("assert"),
 
 /**
  * Gets whether or not a given segment is reachable.
- *
- * @param {CodePathSegment} segment - A segment to get.
+ * @param {CodePathSegment} segment A segment to get.
  * @returns {boolean} `true` if the segment is reachable.
  */
 function isReachable(segment) {
@@ -36,11 +35,10 @@ function isReachable(segment) {
  * When `context.segmentsList` is `[[a, b], [c, d], [e, f]]`, `begin` is `0`, and
  * `end` is `-1`, this creates `[g, h]`. This `g` is from `a`, `c`, and `e`.
  * This `h` is from `b`, `d`, and `f`.
- *
- * @param {ForkContext} context - An instance.
- * @param {number} begin - The first index of the previous segments.
- * @param {number} end - The last index of the previous segments.
- * @param {Function} create - A factory function of new segments.
+ * @param {ForkContext} context An instance.
+ * @param {number} begin The first index of the previous segments.
+ * @param {number} end The last index of the previous segments.
+ * @param {Function} create A factory function of new segments.
  * @returns {CodePathSegment[]} New segments.
  */
 function makeSegments(context, begin, end, create) {
@@ -69,9 +67,8 @@ function makeSegments(context, begin, end, create) {
  * control statement (such as `break`, `continue`) from the `finally` block, the
  * destination's segments may be half of the source segments. In that case, this
  * merges segments.
- *
- * @param {ForkContext} context - An instance.
- * @param {CodePathSegment[]} segments - Segments to merge.
+ * @param {ForkContext} context An instance.
+ * @param {CodePathSegment[]} segments Segments to merge.
  * @returns {CodePathSegment[]} The merged segments.
  */
 function mergeExtraSegments(context, segments) {
@@ -100,10 +97,11 @@ function mergeExtraSegments(context, segments) {
  */
 class ForkContext {
 
+    // eslint-disable-next-line jsdoc/require-description
     /**
-     * @param {IdGenerator} idGenerator - An identifier generator for segments.
-     * @param {ForkContext|null} upper - An upper fork context.
-     * @param {number} count - A number of parallel segments.
+     * @param {IdGenerator} idGenerator An identifier generator for segments.
+     * @param {ForkContext|null} upper An upper fork context.
+     * @param {number} count A number of parallel segments.
      */
     constructor(idGenerator, upper, count) {
         this.idGenerator = idGenerator;
@@ -142,9 +140,8 @@ class ForkContext {
 
     /**
      * Creates new segments from this context.
-     *
-     * @param {number} begin - The first index of previous segments.
-     * @param {number} end - The last index of previous segments.
+     * @param {number} begin The first index of previous segments.
+     * @param {number} end The last index of previous segments.
      * @returns {CodePathSegment[]} New segments.
      */
     makeNext(begin, end) {
@@ -154,9 +151,8 @@ class ForkContext {
     /**
      * Creates new segments from this context.
      * The new segments is always unreachable.
-     *
-     * @param {number} begin - The first index of previous segments.
-     * @param {number} end - The last index of previous segments.
+     * @param {number} begin The first index of previous segments.
+     * @param {number} end The last index of previous segments.
      * @returns {CodePathSegment[]} New segments.
      */
     makeUnreachable(begin, end) {
@@ -167,9 +163,8 @@ class ForkContext {
      * Creates new segments from this context.
      * The new segments don't have connections for previous segments.
      * But these inherit the reachable flag from this context.
-     *
-     * @param {number} begin - The first index of previous segments.
-     * @param {number} end - The last index of previous segments.
+     * @param {number} begin The first index of previous segments.
+     * @param {number} end The last index of previous segments.
      * @returns {CodePathSegment[]} New segments.
      */
     makeDisconnected(begin, end) {
@@ -179,8 +174,7 @@ class ForkContext {
     /**
      * Adds segments into this context.
      * The added segments become the head.
-     *
-     * @param {CodePathSegment[]} segments - Segments to add.
+     * @param {CodePathSegment[]} segments Segments to add.
      * @returns {void}
      */
     add(segments) {
@@ -192,8 +186,7 @@ class ForkContext {
     /**
      * Replaces the head segments with given segments.
      * The current head segments are removed.
-     *
-     * @param {CodePathSegment[]} segments - Segments to add.
+     * @param {CodePathSegment[]} segments Segments to add.
      * @returns {void}
      */
     replaceHead(segments) {
@@ -204,8 +197,7 @@ class ForkContext {
 
     /**
      * Adds all segments of a given fork context into this context.
-     *
-     * @param {ForkContext} context - A fork context to add.
+     * @param {ForkContext} context A fork context to add.
      * @returns {void}
      */
     addAll(context) {
@@ -220,7 +212,6 @@ class ForkContext {
 
     /**
      * Clears all secments in this context.
-     *
      * @returns {void}
      */
     clear() {
@@ -229,8 +220,7 @@ class ForkContext {
 
     /**
      * Creates the root fork context.
-     *
-     * @param {IdGenerator} idGenerator - An identifier generator for segments.
+     * @param {IdGenerator} idGenerator An identifier generator for segments.
      * @returns {ForkContext} New fork context.
      */
     static newRoot(idGenerator) {
@@ -243,9 +233,8 @@ class ForkContext {
 
     /**
      * Creates an empty fork context preceded by a given context.
-     *
-     * @param {ForkContext} parentContext - The parent fork context.
-     * @param {boolean} forkLeavingPath - A flag which shows inside of `finally` block.
+     * @param {ForkContext} parentContext The parent fork context.
+     * @param {boolean} forkLeavingPath A flag which shows inside of `finally` block.
      * @returns {ForkContext} New fork context.
      */
     static newEmpty(parentContext, forkLeavingPath) {

package/lib/linter/code-path-analysis/id-generator.js

@@ -18,8 +18,9 @@
  */
 class IdGenerator {
 
+    // eslint-disable-next-line jsdoc/require-description
     /**
-     * @param {string} prefix - Optional. A prefix of generated ids.
+     * @param {string} prefix Optional. A prefix of generated ids.
      */
     constructor(prefix) {
         this.prefix = String(prefix);
@@ -28,7 +29,6 @@ class IdGenerator {
 
     /**
      * Generates id.
-     *
      * @returns {string} A generated id.
      */
     next() {

package/lib/linter/linter.js

@@ -292,10 +292,15 @@ function getDirectiveComments(filename, ast, ruleMapper, warnInlineConfig) {
         if (!match) {
             return;
         }
-        const lineCommentSupported = /^eslint-disable-(next-)?line$/u.test(match[1]);
+        const directiveText = match[1];
+        const lineCommentSupported = /^eslint-disable-(next-)?line$/u.test(directiveText);
 
-        if (warnInlineConfig && (lineCommentSupported || comment.type === "Block")) {
-            const kind = comment.type === "Block" ? `/*${match[1]}*/` : `//${match[1]}`;
+        if (comment.type === "Line" && !lineCommentSupported) {
+            return;
+        }
+
+        if (warnInlineConfig) {
+            const kind = comment.type === "Block" ? `/*${directiveText}*/` : `//${directiveText}`;
 
             problems.push(createLintingProblem({
                 ruleId: null,
@@ -306,108 +311,101 @@ function getDirectiveComments(filename, ast, ruleMapper, warnInlineConfig) {
             return;
         }
 
-        const directiveValue = trimmedCommentText.slice(match.index + match[1].length);
-        let directiveType = "";
+        if (lineCommentSupported && comment.loc.start.line !== comment.loc.end.line) {
+            const message = `${directiveText} comment should not span multiple lines.`;
 
-        if (lineCommentSupported) {
-            if (comment.loc.start.line === comment.loc.end.line) {
-                directiveType = match[1].slice("eslint-".length);
-            } else {
-                const message = `${match[1]} comment should not span multiple lines.`;
+            problems.push(createLintingProblem({
+                ruleId: null,
+                message,
+                loc: comment.loc
+            }));
+            return;
+        }
 
-                problems.push(createLintingProblem({
-                    ruleId: null,
-                    message,
-                    loc: comment.loc
-                }));
+        const directiveValue = trimmedCommentText.slice(match.index + directiveText.length);
+
+        switch (directiveText) {
+            case "eslint-disable":
+            case "eslint-enable":
+            case "eslint-disable-next-line":
+            case "eslint-disable-line": {
+                const directiveType = directiveText.slice("eslint-".length);
+                const options = { type: directiveType, loc: comment.loc, value: directiveValue, ruleMapper };
+                const { directives, directiveProblems } = createDisableDirectives(options);
+
+                disableDirectives.push(...directives);
+                problems.push(...directiveProblems);
+                break;
             }
-        } else if (comment.type === "Block") {
-            switch (match[1]) {
-                case "exported":
-                    Object.assign(exportedVariables, commentParser.parseStringConfig(directiveValue, comment));
-                    break;
 
-                case "globals":
-                case "global":
-                    for (const [id, { value }] of Object.entries(commentParser.parseStringConfig(directiveValue, comment))) {
-                        let normalizedValue;
+            case "exported":
+                Object.assign(exportedVariables, commentParser.parseStringConfig(directiveValue, comment));
+                break;
+
+            case "globals":
+            case "global":
+                for (const [id, { value }] of Object.entries(commentParser.parseStringConfig(directiveValue, comment))) {
+                    let normalizedValue;
+
+                    try {
+                        normalizedValue = ConfigOps.normalizeConfigGlobal(value);
+                    } catch (err) {
+                        problems.push(createLintingProblem({
+                            ruleId: null,
+                            loc: comment.loc,
+                            message: err.message
+                        }));
+                        continue;
+                    }
+
+                    if (enabledGlobals[id]) {
+                        enabledGlobals[id].comments.push(comment);
+                        enabledGlobals[id].value = normalizedValue;
+                    } else {
+                        enabledGlobals[id] = {
+                            comments: [comment],
+                            value: normalizedValue
+                        };
+                    }
+                }
+                break;
+
+            case "eslint": {
+                const parseResult = commentParser.parseJsonConfig(directiveValue, comment.loc);
+
+                if (parseResult.success) {
+                    Object.keys(parseResult.config).forEach(name => {
+                        const rule = ruleMapper(name);
+                        const ruleValue = parseResult.config[name];
+
+                        if (rule === null) {
+                            problems.push(createLintingProblem({ ruleId: name, loc: comment.loc }));
+                            return;
+                        }
 
                         try {
-                            normalizedValue = ConfigOps.normalizeConfigGlobal(value);
+                            validator.validateRuleOptions(rule, name, ruleValue);
                         } catch (err) {
                             problems.push(createLintingProblem({
-                                ruleId: null,
-                                loc: comment.loc,
-                                message: err.message
+                                ruleId: name,
+                                message: err.message,
+                                loc: comment.loc
                             }));
-                            continue;
-                        }
 
-                        if (enabledGlobals[id]) {
-                            enabledGlobals[id].comments.push(comment);
-                            enabledGlobals[id].value = normalizedValue;
-                        } else {
-                            enabledGlobals[id] = {
-                                comments: [comment],
-                                value: normalizedValue
-                            };
+                            // do not apply the config, if found invalid options.
+                            return;
                         }
-                    }
-                    break;
-
-                case "eslint-disable":
-                    directiveType = "disable";
-                    break;
-
-                case "eslint-enable":
-                    directiveType = "enable";
-                    break;
-
-                case "eslint": {
-                    const parseResult = commentParser.parseJsonConfig(directiveValue, comment.loc);
-
-                    if (parseResult.success) {
-                        Object.keys(parseResult.config).forEach(name => {
-                            const rule = ruleMapper(name);
-                            const ruleValue = parseResult.config[name];
-
-                            if (rule === null) {
-                                problems.push(createLintingProblem({ ruleId: name, loc: comment.loc }));
-                                return;
-                            }
-
-                            try {
-                                validator.validateRuleOptions(rule, name, ruleValue);
-                            } catch (err) {
-                                problems.push(createLintingProblem({
-                                    ruleId: name,
-                                    message: err.message,
-                                    loc: comment.loc
-                                }));
-
-                                // do not apply the config, if found invalid options.
-                                return;
-                            }
-
-                            configuredRules[name] = ruleValue;
-                        });
-                    } else {
-                        problems.push(parseResult.error);
-                    }
 
-                    break;
+                        configuredRules[name] = ruleValue;
+                    });
+                } else {
+                    problems.push(parseResult.error);
                 }
 
-                // no default
+                break;
             }
-        }
-
-        if (directiveType !== "") {
-            const options = { type: directiveType, loc: comment.loc, value: directiveValue, ruleMapper };
-            const { directives, directiveProblems } = createDisableDirectives(options);
 
-            disableDirectives.push(...directives);
-            problems.push(...directiveProblems);
+            // no default
         }
     });
 
@@ -438,7 +436,7 @@ const eslintEnvPattern = /\/\*\s*eslint-env\s(.+?)\*\//gu;
 
 /**
  * Checks whether or not there is a comment which has "eslint-env *" in a given text.
- * @param {string} text - A source code text to check.
+ * @param {string} text A source code text to check.
  * @returns {Object|null} A result of parseListConfig() with "eslint-env *" comment.
  */
 function findEslintEnv(text) {
@@ -555,8 +553,7 @@ function resolveGlobals(providedGlobals, enabledEnvironments) {
 
 /**
  * Strips Unicode BOM from a given text.
- *
- * @param {string} text - A text to strip.
+ * @param {string} text A text to strip.
  * @returns {string} The stripped text.
  */
 function stripUnicodeBOM(text) {
@@ -669,6 +666,8 @@ function parse(text, parser, providedParserOptions, filePath) {
         // If the message includes a leading line number, strip it:
         const message = `Parsing error: ${ex.message.replace(/^line \d+:/iu, "").trim()}`;
 
+        debug("%s\n%s", message, ex.stack);
+
         return {
             success: false,
             error: {
@@ -813,9 +812,10 @@ const BASE_TRAVERSAL_CONTEXT = Object.freeze(
  * @param {Object} settings The settings that were enabled in the config
  * @param {string} filename The reported filename of the code
  * @param {boolean} disableFixes If true, it doesn't make `fix` properties.
+ * @param {string | undefined} cwd cwd of the cli
  * @returns {Problem[]} An array of reported problems
  */
-function runRules(sourceCode, configuredRules, ruleMapper, parserOptions, parserName, settings, filename, disableFixes) {
+function runRules(sourceCode, configuredRules, ruleMapper, parserOptions, parserName, settings, filename, disableFixes, cwd) {
     const emitter = createEmitter();
     const nodeQueue = [];
     let currentNode = sourceCode.ast;
@@ -842,6 +842,7 @@ function runRules(sourceCode, configuredRules, ruleMapper, parserOptions, parser
             {
                 getAncestors: () => getAncestors(currentNode),
                 getDeclaredVariables: sourceCode.scopeManager.getDeclaredVariables.bind(sourceCode.scopeManager),
+                getCwd: () => cwd,
                 getFilename: () => filename,
                 getScope: () => getScope(sourceCode.scopeManager, currentNode),
                 getSourceCode: () => sourceCode,
@@ -988,6 +989,24 @@ function getRule(slots, ruleId) {
     );
 }
 
+/**
+ * Normalize the value of the cwd
+ * @param {string | undefined} cwd raw value of the cwd, path to a directory that should be considered as the current working directory, can be undefined.
+ * @returns {string | undefined} normalized cwd
+ */
+function normalizeCwd(cwd) {
+    if (cwd) {
+        return cwd;
+    }
+    if (typeof process === "object") {
+        return process.cwd();
+    }
+
+    // It's more explicit to assign the undefined
+    // eslint-disable-next-line no-undefined
+    return undefined;
+}
+
 /**
  * The map to store private data.
  * @type {WeakMap<Linter, LinterInternalSlots>}
@@ -1004,8 +1023,14 @@ const internalSlotsMap = new WeakMap();
  */
 class Linter {
 
-    constructor() {
+    /**
+     * Initialize the Linter.
+     * @param {Object} [config] the config object
+     * @param {string} [config.cwd]  path to a directory that should be considered as the current working directory, can be undefined.
+     */
+    constructor({ cwd } = {}) {
         internalSlotsMap.set(this, {
+            cwd: normalizeCwd(cwd),
             lastConfigArray: null,
             lastSourceCode: null,
             parserMap: new Map([["espree", espree]]),
@@ -1137,7 +1162,8 @@ class Linter {
                 parserName,
                 settings,
                 options.filename,
-                options.disableFixes
+                options.disableFixes,
+                slots.cwd
             );
         } catch (err) {
             err.message += `\nOccurred while linting ${options.filename}`;

package/lib/linter/node-event-generator.js

@@ -202,6 +202,7 @@ const parseSelector = lodash.memoize(rawSelector => {
  */
 class NodeEventGenerator {
 
+    // eslint-disable-next-line jsdoc/require-description
     /**
      * @param {SafeEmitter} emitter
      * An SafeEmitter which is the destination of events. This emitter must already
@@ -286,7 +287,7 @@ class NodeEventGenerator {
 
     /**
      * Emits an event of entering AST node.
-     * @param {ASTNode} node - A node which was entered.
+     * @param {ASTNode} node A node which was entered.
      * @returns {void}
      */
     enterNode(node) {
@@ -298,7 +299,7 @@ class NodeEventGenerator {
 
     /**
      * Emits an event of leaving AST node.
-     * @param {ASTNode} node - A node which was left.
+     * @param {ASTNode} node A node which was left.
      * @returns {void}
      */
     leaveNode(node) {

package/lib/linter/report-translator.js

@@ -26,6 +26,7 @@ const interpolate = require("./interpolate");
  * @property {Object} [data] Optional data to use to fill in placeholders in the
  *      message.
  * @property {Function} [fix] The function to call that creates a fix command.
+ * @property {Array<{desc?: string, messageId?: string, fix: Function}>} suggest Suggestion descriptions and functions to create a the associated fixes.
  */
 
 /**
@@ -34,14 +35,15 @@ const interpolate = require("./interpolate");
  * @property {string} ruleId
  * @property {(0|1|2)} severity
  * @property {(string|undefined)} message
- * @property {(string|undefined)} messageId
+ * @property {(string|undefined)} [messageId]
  * @property {number} line
  * @property {number} column
- * @property {(number|undefined)} endLine
- * @property {(number|undefined)} endColumn
+ * @property {(number|undefined)} [endLine]
+ * @property {(number|undefined)} [endColumn]
  * @property {(string|null)} nodeType
  * @property {string} source
- * @property {({text: string, range: (number[]|null)}|null)} fix
+ * @property {({text: string, range: (number[]|null)}|null)} [fix]
+ * @property {Array<{text: string, range: (number[]|null)}|null>} [suggestions]
  */
 
 //------------------------------------------------------------------------------
@@ -182,6 +184,29 @@ function normalizeFixes(descriptor, sourceCode) {
     return fix;
 }
 
+/**
+ * Gets an array of suggestion objects from the given descriptor.
+ * @param {MessageDescriptor} descriptor The report descriptor.
+ * @param {SourceCode} sourceCode The source code object to get text between fixes.
+ * @param {Object} messages Object of meta messages for the rule.
+ * @returns {Array<SuggestionResult>} The suggestions for the descriptor
+ */
+function mapSuggestions(descriptor, sourceCode, messages) {
+    if (!descriptor.suggest || !Array.isArray(descriptor.suggest)) {
+        return [];
+    }
+
+    return descriptor.suggest.map(suggestInfo => {
+        const computedDesc = suggestInfo.desc || messages[suggestInfo.messageId];
+
+        return {
+            ...suggestInfo,
+            desc: interpolate(computedDesc, suggestInfo.data),
+            fix: normalizeFixes(suggestInfo, sourceCode)
+        };
+    });
+}
+
 /**
  * Creates information about the report from a descriptor
  * @param {Object} options Information about the problem
@@ -192,6 +217,7 @@ function normalizeFixes(descriptor, sourceCode) {
  * @param {string} [options.messageId] The error message ID.
  * @param {{start: SourceLocation, end: (SourceLocation|null)}} options.loc Start and end location
  * @param {{text: string, range: (number[]|null)}} options.fix The fix object
+ * @param {Array<{text: string, range: (number[]|null)}>} options.suggestions The array of suggestions objects
  * @returns {function(...args): ReportInfo} Function that returns information about the report
  */
 function createProblem(options) {
@@ -221,9 +247,47 @@ function createProblem(options) {
         problem.fix = options.fix;
     }
 
+    if (options.suggestions && options.suggestions.length > 0) {
+        problem.suggestions = options.suggestions;
+    }
+
     return problem;
 }
 
+/**
+ * Validates that suggestions are properly defined. Throws if an error is detected.
+ * @param {Array<{ desc?: string, messageId?: string }>} suggest The incoming suggest data.
+ * @param {Object} messages Object of meta messages for the rule.
+ * @returns {void}
+ */
+function validateSuggestions(suggest, messages) {
+    if (suggest && Array.isArray(suggest)) {
+        suggest.forEach(suggestion => {
+            if (suggestion.messageId) {
+                const { messageId } = suggestion;
+
+                if (!messages) {
+                    throw new TypeError(`context.report() called with a suggest option with a messageId '${messageId}', but no messages were present in the rule metadata.`);
+                }
+
+                if (!messages[messageId]) {
+                    throw new TypeError(`context.report() called with a suggest option with a messageId '${messageId}' which is not present in the 'messages' config: ${JSON.stringify(messages, null, 2)}`);
+                }
+
+                if (suggestion.desc) {
+                    throw new TypeError("context.report() called with a suggest option that defines both a 'messageId' and an 'desc'. Please only pass one.");
+                }
+            } else if (!suggestion.desc) {
+                throw new TypeError("context.report() called with a suggest option that doesn't have either a `desc` or `messageId`");
+            }
+
+            if (typeof suggestion.fix !== "function") {
+                throw new TypeError(`context.report() called with a suggest option without a fix function. See: ${suggestion}`);
+            }
+        });
+    }
+}
+
 /**
  * Returns a function that converts the arguments of a `context.report` call from a rule into a reported
  * problem for the Node.js API.
@@ -242,17 +306,17 @@ module.exports = function createReportTranslator(metadata) {
      */
     return (...args) => {
         const descriptor = normalizeMultiArgReportCall(...args);
+        const messages = metadata.messageIds;
 
         assertValidNodeInfo(descriptor);
 
         let computedMessage;
 
         if (descriptor.messageId) {
-            if (!metadata.messageIds) {
+            if (!messages) {
                 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.");
@@ -267,6 +331,7 @@ module.exports = function createReportTranslator(metadata) {
             throw new TypeError("Missing `message` property in report() call; add a message that describes the linting problem.");
         }
 
+        validateSuggestions(descriptor.suggest, messages);
 
         return createProblem({
             ruleId: metadata.ruleId,
@@ -275,7 +340,8 @@ module.exports = function createReportTranslator(metadata) {
             message: interpolate(computedMessage, descriptor.data),
             messageId: descriptor.messageId,
             loc: normalizeReportLoc(descriptor),
-            fix: metadata.disableFixes ? null : normalizeFixes(descriptor, metadata.sourceCode)
+            fix: metadata.disableFixes ? null : normalizeFixes(descriptor, metadata.sourceCode),
+            suggestions: metadata.disableFixes ? [] : mapSuggestions(descriptor, metadata.sourceCode, messages)
         });
     };
 };