eslint 8.57.0 → 9.2.0

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

@@ -18,8 +18,12 @@ const
         directivesPattern
     } = require("../shared/directives"),
 
-    /* eslint-disable-next-line n/no-restricted-require -- Too messy to figure out right now. */
+    /* eslint-disable n/no-restricted-require -- Should eventually be moved into SourceCode. */
+    CodePathAnalyzer = require("../linter/code-path-analysis/code-path-analyzer"),
+    createEmitter = require("../linter/safe-emitter"),
     ConfigCommentParser = require("../linter/config-comment-parser"),
+    /* eslint-enable n/no-restricted-require -- Should eventually be moved into SourceCode. */
+
     eslintScope = require("eslint-scope");
 
 //------------------------------------------------------------------------------
@@ -34,6 +38,16 @@ const
 
 const commentParser = new ConfigCommentParser();
 
+const CODE_PATH_EVENTS = [
+    "onCodePathStart",
+    "onCodePathEnd",
+    "onCodePathSegmentStart",
+    "onCodePathSegmentEnd",
+    "onCodePathSegmentLoop",
+    "onUnreachableCodePathSegmentStart",
+    "onUnreachableCodePathSegmentEnd"
+];
+
 /**
  * Validates that the given AST has the required information.
  * @param {ASTNode} ast The Program node of the AST to check.
@@ -300,6 +314,115 @@ function markExportedVariables(globalScope, variables) {
 
 }
 
+const STEP_KIND = {
+    visit: 1,
+    call: 2
+};
+
+/**
+ * A class to represent a step in the traversal process.
+ */
+class TraversalStep {
+
+    /**
+     * The type of the step.
+     * @type {string}
+     */
+    type;
+
+    /**
+     * The kind of the step. Represents the same data as the `type` property
+     * but it's a number for performance.
+     * @type {number}
+     */
+    kind;
+
+    /**
+     * The target of the step.
+     * @type {ASTNode|string}
+     */
+    target;
+
+    /**
+     * The phase of the step.
+     * @type {number|undefined}
+     */
+    phase;
+
+    /**
+     * The arguments of the step.
+     * @type {Array<any>}
+     */
+    args;
+
+    /**
+     * Creates a new instance.
+     * @param {Object} options The options for the step.
+     * @param {string} options.type The type of the step.
+     * @param {ASTNode|string} options.target The target of the step.
+     * @param {number|undefined} [options.phase] The phase of the step.
+     * @param {Array<any>} options.args The arguments of the step.
+     * @returns {void}
+     */
+    constructor({ type, target, phase, args }) {
+        this.type = type;
+        this.kind = STEP_KIND[type];
+        this.target = target;
+        this.phase = phase;
+        this.args = args;
+    }
+}
+
+/**
+ * A class to represent a directive comment.
+ */
+class Directive {
+
+    /**
+     * The type of directive.
+     * @type {"disable"|"enable"|"disable-next-line"|"disable-line"}
+     * @readonly
+     */
+    type;
+
+    /**
+     * The node representing the directive.
+     * @type {ASTNode|Comment}
+     * @readonly
+     */
+    node;
+
+    /**
+     * Everything after the "eslint-disable" portion of the directive,
+     * but before the "--" that indicates the justification.
+     * @type {string}
+     * @readonly
+     */
+    value;
+
+    /**
+     * The justification for the directive.
+     * @type {string}
+     * @readonly
+     */
+    justification;
+
+    /**
+     * Creates a new instance.
+     * @param {Object} options The options for the directive.
+     * @param {"disable"|"enable"|"disable-next-line"|"disable-line"} options.type The type of directive.
+     * @param {ASTNode|Comment} options.node The node representing the directive.
+     * @param {string} options.value The value of the directive.
+     * @param {string} options.justification The justification for the directive.
+     */
+    constructor({ type, node, value, justification }) {
+        this.type = type;
+        this.node = node;
+        this.value = value;
+        this.justification = justification;
+    }
+}
+
 //------------------------------------------------------------------------------
 // Public Interface
 //------------------------------------------------------------------------------
@@ -311,6 +434,12 @@ const caches = Symbol("caches");
  */
 class SourceCode extends TokenStore {
 
+    /**
+     * The cache of steps that were taken while traversing the source code.
+     * @type {Array<TraversalStep>}
+     */
+    #steps;
+
     /**
      * @param {string|Object} textOrConfig The source code text or config object.
      * @param {string} textOrConfig.text The source code text.
@@ -415,13 +544,10 @@ class SourceCode extends TokenStore {
          * and uses match.index to get the correct line start indices.
          */
         while ((match = lineEndingPattern.exec(this.text))) {
-            this.lines.push(this.text.slice(this.lineStartIndices[this.lineStartIndices.length - 1], match.index));
+            this.lines.push(this.text.slice(this.lineStartIndices.at(-1), match.index));
             this.lineStartIndices.push(match.index + match[0].length);
         }
-        this.lines.push(this.text.slice(this.lineStartIndices[this.lineStartIndices.length - 1]));
-
-        // Cache for comments found using getComments().
-        this._commentCache = new WeakMap();
+        this.lines.push(this.text.slice(this.lineStartIndices.at(-1)));
 
         // don't allow further modification of this object
         Object.freeze(this);
@@ -472,81 +598,6 @@ class SourceCode extends TokenStore {
         return this.ast.comments;
     }
 
-    /**
-     * Gets all comments for the given node.
-     * @param {ASTNode} node The AST node to get the comments for.
-     * @returns {Object} An object containing a leading and trailing array
-     *      of comments indexed by their position.
-     * @public
-     * @deprecated replaced by getCommentsBefore(), getCommentsAfter(), and getCommentsInside().
-     */
-    getComments(node) {
-        if (this._commentCache.has(node)) {
-            return this._commentCache.get(node);
-        }
-
-        const comments = {
-            leading: [],
-            trailing: []
-        };
-
-        /*
-         * Return all comments as leading comments of the Program node when
-         * there is no executable code.
-         */
-        if (node.type === "Program") {
-            if (node.body.length === 0) {
-                comments.leading = node.comments;
-            }
-        } else {
-
-            /*
-             * Return comments as trailing comments of nodes that only contain
-             * comments (to mimic the comment attachment behavior present in Espree).
-             */
-            if ((node.type === "BlockStatement" || node.type === "ClassBody") && node.body.length === 0 ||
-                node.type === "ObjectExpression" && node.properties.length === 0 ||
-                node.type === "ArrayExpression" && node.elements.length === 0 ||
-                node.type === "SwitchStatement" && node.cases.length === 0
-            ) {
-                comments.trailing = this.getTokens(node, {
-                    includeComments: true,
-                    filter: isCommentToken
-                });
-            }
-
-            /*
-             * Iterate over tokens before and after node and collect comment tokens.
-             * Do not include comments that exist outside of the parent node
-             * to avoid duplication.
-             */
-            let currentToken = this.getTokenBefore(node, { includeComments: true });
-
-            while (currentToken && isCommentToken(currentToken)) {
-                if (node.parent && node.parent.type !== "Program" && (currentToken.start < node.parent.start)) {
-                    break;
-                }
-                comments.leading.push(currentToken);
-                currentToken = this.getTokenBefore(currentToken, { includeComments: true });
-            }
-
-            comments.leading.reverse();
-
-            currentToken = this.getTokenAfter(node, { includeComments: true });
-
-            while (currentToken && isCommentToken(currentToken)) {
-                if (node.parent && node.parent.type !== "Program" && (currentToken.end > node.parent.end)) {
-                    break;
-                }
-                comments.trailing.push(currentToken);
-                currentToken = this.getTokenAfter(currentToken, { includeComments: true });
-            }
-        }
-
-        this._commentCache.set(node, comments);
-        return comments;
-    }
-
     /**
      * Retrieves the JSDoc comment for a given node.
      * @param {ASTNode} node The AST node to get the comment for.
@@ -701,14 +752,14 @@ class SourceCode extends TokenStore {
          * See getIndexFromLoc for the motivation for this special case.
          */
         if (index === this.text.length) {
-            return { line: this.lines.length, column: this.lines[this.lines.length - 1].length };
+            return { line: this.lines.length, column: this.lines.at(-1).length };
         }
 
         /*
          * To figure out which line index is on, determine the last place at which index could
          * be inserted into lineStartIndices to keep the list sorted.
          */
-        const lineNumber = index >= this.lineStartIndices[this.lineStartIndices.length - 1]
+        const lineNumber = index >= this.lineStartIndices.at(-1)
             ? this.lineStartIndices.length
             : this.lineStartIndices.findIndex(el => index < el);
 
@@ -920,6 +971,84 @@ class SourceCode extends TokenStore {
         return configNodes;
     }
 
+    /**
+     * Returns an all directive nodes that enable or disable rules along with any problems
+     * encountered while parsing the directives.
+     * @returns {{problems:Array<Problem>,directives:Array<Directive>}} Information
+     *      that ESLint needs to further process the directives.
+     */
+    getDisableDirectives() {
+
+        // check the cache first
+        const cachedDirectives = this[caches].get("disableDirectives");
+
+        if (cachedDirectives) {
+            return cachedDirectives;
+        }
+
+        const problems = [];
+        const directives = [];
+
+        this.getInlineConfigNodes().forEach(comment => {
+            const { directivePart, justificationPart } = commentParser.extractDirectiveComment(comment.value);
+
+            // Step 1: Extract the directive text
+            const match = directivesPattern.exec(directivePart);
+
+            if (!match) {
+                return;
+            }
+
+            const directiveText = match[1];
+
+            // Step 2: Extract the directive value
+            const lineCommentSupported = /^eslint-disable-(next-)?line$/u.test(directiveText);
+
+            if (comment.type === "Line" && !lineCommentSupported) {
+                return;
+            }
+
+            // Step 3: Validate the directive does not span multiple lines
+            if (directiveText === "eslint-disable-line" && comment.loc.start.line !== comment.loc.end.line) {
+                const message = `${directiveText} comment should not span multiple lines.`;
+
+                problems.push({
+                    ruleId: null,
+                    message,
+                    loc: comment.loc
+                });
+                return;
+            }
+
+            // Step 4: Extract the directive value and create the Directive object
+            const directiveValue = directivePart.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);
+
+                    directives.push(new Directive({
+                        type: directiveType,
+                        node: comment,
+                        value: directiveValue,
+                        justification: justificationPart
+                    }));
+                }
+
+                // no default
+            }
+        });
+
+        const result = { problems, directives };
+
+        this[caches].set("disableDirectives", result);
+
+        return result;
+    }
+
     /**
      * Applies language options sent in from the core.
      * @param {Object} languageOptions The language options for this run.
@@ -934,7 +1063,7 @@ class SourceCode extends TokenStore {
          * https://github.com/eslint/eslint/issues/16302
          */
         const configGlobals = Object.assign(
-            {},
+            Object.create(null), // https://github.com/eslint/eslint/issues/18363
             getGlobalsForEcmaVersion(languageOptions.ecmaVersion),
             languageOptions.sourceType === "commonjs" ? globals.commonjs : void 0,
             languageOptions.globals
@@ -963,7 +1092,7 @@ class SourceCode extends TokenStore {
 
             switch (directiveText) {
                 case "exported":
-                    Object.assign(exportedVariables, commentParser.parseStringConfig(directiveValue, comment));
+                    Object.assign(exportedVariables, commentParser.parseListConfig(directiveValue, comment));
                     break;
 
                 case "globals":
@@ -1050,6 +1179,91 @@ class SourceCode extends TokenStore {
 
     }
 
+    /**
+     * Traverse the source code and return the steps that were taken.
+     * @returns {Array<TraversalStep>} The steps that were taken while traversing the source code.
+     */
+    traverse() {
+
+        // Because the AST doesn't mutate, we can cache the steps
+        if (this.#steps) {
+            return this.#steps;
+        }
+
+        const steps = this.#steps = [];
+
+        /*
+         * This logic works for any AST, not just ESTree. Because ESLint has allowed
+         * custom parsers to return any AST, we need to ensure that the traversal
+         * logic works for any AST.
+         */
+        const emitter = createEmitter();
+        let analyzer = {
+            enterNode(node) {
+                steps.push(new TraversalStep({
+                    type: "visit",
+                    target: node,
+                    phase: 1,
+                    args: [node, node.parent]
+                }));
+            },
+            leaveNode(node) {
+                steps.push(new TraversalStep({
+                    type: "visit",
+                    target: node,
+                    phase: 2,
+                    args: [node, node.parent]
+                }));
+            },
+            emitter
+        };
+
+        /*
+         * We do code path analysis for ESTree only. Code path analysis is not
+         * necessary for other ASTs, and it's also not possible to do for other
+         * ASTs because the necessary information is not available.
+         *
+         * Generally speaking, we can tell that the AST is an ESTree if it has a
+         * Program node at the top level. This is not a perfect heuristic, but it
+         * is good enough for now.
+         */
+        const isESTree = this.ast.type === "Program";
+
+        if (isESTree) {
+            analyzer = new CodePathAnalyzer(analyzer);
+
+            CODE_PATH_EVENTS.forEach(eventName => {
+                emitter.on(eventName, (...args) => {
+                    steps.push(new TraversalStep({
+                        type: "call",
+                        target: eventName,
+                        args
+                    }));
+                });
+            });
+        }
+
+        /*
+         * The actual AST traversal is done by the `Traverser` class. This class
+         * is responsible for walking the AST and calling the appropriate methods
+         * on the `analyzer` object, which is appropriate for the given AST.
+         */
+        Traverser.traverse(this.ast, {
+            enter(node, parent) {
+
+                // save the parent node on a property for backwards compatibility
+                node.parent = parent;
+
+                analyzer.enterNode(node);
+            },
+            leave(node) {
+                analyzer.leaveNode(node);
+            },
+            visitorKeys: this.visitorKeys
+        });
+
+        return steps;
+    }
 }
 
 module.exports = SourceCode;

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

@@ -9,7 +9,7 @@
 //------------------------------------------------------------------------------
 
 const Cursor = require("./cursor");
-const utils = require("./utils");
+const { getLastIndex, getFirstIndex } = require("./utils");
 
 //------------------------------------------------------------------------------
 // Exports
@@ -31,8 +31,8 @@ module.exports = class BackwardTokenCursor extends Cursor {
     constructor(tokens, comments, indexMap, startLoc, endLoc) {
         super();
         this.tokens = tokens;
-        this.index = utils.getLastIndex(tokens, indexMap, endLoc);
-        this.indexEnd = utils.getFirstIndex(tokens, indexMap, startLoc);
+        this.index = getLastIndex(tokens, indexMap, endLoc);
+        this.indexEnd = getFirstIndex(tokens, indexMap, startLoc);
     }
 
     /** @inheritdoc */

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

@@ -86,5 +86,7 @@ class CursorFactory {
 // Exports
 //------------------------------------------------------------------------------
 
-exports.forward = new CursorFactory(ForwardTokenCursor, ForwardTokenCommentCursor);
-exports.backward = new CursorFactory(BackwardTokenCursor, BackwardTokenCommentCursor);
+module.exports = {
+    forward: new CursorFactory(ForwardTokenCursor, ForwardTokenCommentCursor),
+    backward: new CursorFactory(BackwardTokenCursor, BackwardTokenCommentCursor)
+};

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

@@ -9,7 +9,7 @@
 //------------------------------------------------------------------------------
 
 const Cursor = require("./cursor");
-const utils = require("./utils");
+const { getFirstIndex, search } = require("./utils");
 
 //------------------------------------------------------------------------------
 // Exports
@@ -32,8 +32,8 @@ module.exports = class ForwardTokenCommentCursor extends Cursor {
         super();
         this.tokens = tokens;
         this.comments = comments;
-        this.tokenIndex = utils.getFirstIndex(tokens, indexMap, startLoc);
-        this.commentIndex = utils.search(comments, startLoc);
+        this.tokenIndex = getFirstIndex(tokens, indexMap, startLoc);
+        this.commentIndex = search(comments, startLoc);
         this.border = endLoc;
     }
 

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

@@ -9,7 +9,7 @@
 //------------------------------------------------------------------------------
 
 const Cursor = require("./cursor");
-const utils = require("./utils");
+const { getFirstIndex, getLastIndex } = require("./utils");
 
 //------------------------------------------------------------------------------
 // Exports
@@ -31,8 +31,8 @@ module.exports = class ForwardTokenCursor extends Cursor {
     constructor(tokens, comments, indexMap, startLoc, endLoc) {
         super();
         this.tokens = tokens;
-        this.index = utils.getFirstIndex(tokens, indexMap, startLoc);
-        this.indexEnd = utils.getLastIndex(tokens, indexMap, endLoc);
+        this.index = getFirstIndex(tokens, indexMap, startLoc);
+        this.indexEnd = getLastIndex(tokens, indexMap, endLoc);
     }
 
     /** @inheritdoc */

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

@@ -37,8 +37,8 @@ function createIndexMap(tokens, comments) {
     const map = Object.create(null);
     let tokenIndex = 0;
     let commentIndex = 0;
-    let nextStart = 0;
-    let range = null;
+    let nextStart;
+    let range;
 
     while (tokenIndex < tokens.length || commentIndex < comments.length) {
         nextStart = (commentIndex < comments.length) ? comments[commentIndex].range[0] : Number.MAX_SAFE_INTEGER;

package/lib/unsupported-api.js

@@ -12,9 +12,8 @@
 //-----------------------------------------------------------------------------
 
 const { FileEnumerator } = require("./cli-engine/file-enumerator");
-const { FlatESLint, shouldUseFlatConfig } = require("./eslint/flat-eslint");
-const FlatRuleTester = require("./rule-tester/flat-rule-tester");
-const { ESLint } = require("./eslint/eslint");
+const { ESLint: FlatESLint, shouldUseFlatConfig } = require("./eslint/eslint");
+const { LegacyESLint } = require("./eslint/legacy-eslint");
 
 //-----------------------------------------------------------------------------
 // Exports
@@ -24,7 +23,6 @@ module.exports = {
     builtinRules: require("./rules"),
     FlatESLint,
     shouldUseFlatConfig,
-    FlatRuleTester,
     FileEnumerator,
-    LegacyESLint: ESLint
+    LegacyESLint
 };

package/messages/no-config-found.js

@@ -6,7 +6,7 @@ module.exports = function(it) {
     return `
 ESLint couldn't find a configuration file. To set up a configuration file for this project, please run:
 
-    npm init @eslint/config
+    npm init @eslint/config@latest
 
 ESLint looked for configuration files in ${directoryPath} and its ancestors. If it found none, it then looked in your home directory.
 

package/messages/plugin-conflict.js

@@ -15,7 +15,7 @@ module.exports = function(it) {
 
 Please remove the "plugins" setting from either config or remove either plugin installation.
 
-If you still can't figure out the problem, please stop by https://eslint.org/chat/help to chat with the team.
+If you still can't figure out the problem, please see https://eslint.org/docs/latest/use/troubleshooting.
 `;
 
     return result;

package/messages/plugin-invalid.js

@@ -11,6 +11,6 @@ module.exports = function(it) {
 
 "${configName}" was referenced from the config file in "${importerName}".
 
-If you still can't figure out the problem, please stop by https://eslint.org/chat/help to chat with the team.
+If you still can't figure out the problem, please see https://eslint.org/docs/latest/use/troubleshooting.
 `.trimStart();
 };

package/messages/plugin-missing.js

@@ -14,6 +14,6 @@ It's likely that the plugin isn't installed correctly. Try reinstalling by runni
 
 The plugin "${pluginName}" was referenced from the config file in "${importerName}".
 
-If you still can't figure out the problem, please stop by https://eslint.org/chat/help to chat with the team.
+If you still can't figure out the problem, please see https://eslint.org/docs/latest/use/troubleshooting.
 `.trimStart();
 };