eslint 9.4.0 → 9.5.0

package/lib/languages/js/index.js

@@ -0,0 +1,247 @@
+/**
+ * @fileoverview JavaScript Language Object
+ * @author Nicholas C. Zakas
+ */
+
+"use strict";
+
+//-----------------------------------------------------------------------------
+// Requirements
+//-----------------------------------------------------------------------------
+
+const { SourceCode } = require("./source-code");
+const createDebug = require("debug");
+const astUtils = require("../../shared/ast-utils");
+const eslintScope = require("eslint-scope");
+const evk = require("eslint-visitor-keys");
+const { validateLanguageOptions } = require("./validate-language-options");
+
+//-----------------------------------------------------------------------------
+// Type Definitions
+//-----------------------------------------------------------------------------
+
+/** @typedef {import("../../linter/vfile").VFile} VFile */
+
+//-----------------------------------------------------------------------------
+// Helpers
+//-----------------------------------------------------------------------------
+
+const debug = createDebug("eslint:languages:js");
+const DEFAULT_ECMA_VERSION = 5;
+
+/**
+ * Analyze scope of the given AST.
+ * @param {ASTNode} ast The `Program` node to analyze.
+ * @param {LanguageOptions} languageOptions The parser options.
+ * @param {Record<string, string[]>} visitorKeys The visitor keys.
+ * @returns {ScopeManager} The analysis result.
+ */
+function analyzeScope(ast, languageOptions, visitorKeys) {
+    const parserOptions = languageOptions.parserOptions;
+    const ecmaFeatures = parserOptions.ecmaFeatures || {};
+    const ecmaVersion = languageOptions.ecmaVersion || DEFAULT_ECMA_VERSION;
+
+    return eslintScope.analyze(ast, {
+        ignoreEval: true,
+        nodejsScope: ecmaFeatures.globalReturn,
+        impliedStrict: ecmaFeatures.impliedStrict,
+        ecmaVersion: typeof ecmaVersion === "number" ? ecmaVersion : 6,
+        sourceType: languageOptions.sourceType || "script",
+        childVisitorKeys: visitorKeys || evk.KEYS,
+        fallback: evk.getKeys
+    });
+}
+
+//-----------------------------------------------------------------------------
+// Exports
+//-----------------------------------------------------------------------------
+
+module.exports = {
+
+    fileType: "text",
+    lineStart: 1,
+    columnStart: 0,
+    nodeTypeKey: "type",
+    visitorKeys: evk.KEYS,
+
+    validateLanguageOptions,
+
+    /**
+     * Determines if a given node matches a given selector class.
+     * @param {string} className The class name to check.
+     * @param {ASTNode} node The node to check.
+     * @param {Array<ASTNode>} ancestry The ancestry of the node.
+     * @returns {boolean} True if there's a match, false if not.
+     * @throws {Error} When an unknown class name is passed.
+     */
+    matchesSelectorClass(className, node, ancestry) {
+
+        /*
+         * Copyright (c) 2013, Joel Feenstra
+         * All rights reserved.
+         *
+         * Redistribution and use in source and binary forms, with or without
+         * modification, are permitted provided that the following conditions are met:
+         *    * Redistributions of source code must retain the above copyright
+         *      notice, this list of conditions and the following disclaimer.
+         *    * Redistributions in binary form must reproduce the above copyright
+         *      notice, this list of conditions and the following disclaimer in the
+         *      documentation and/or other materials provided with the distribution.
+         *    * Neither the name of the ESQuery nor the names of its contributors may
+         *      be used to endorse or promote products derived from this software without
+         *      specific prior written permission.
+         *
+         * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+         * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+         * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+         * DISCLAIMED. IN NO EVENT SHALL JOEL FEENSTRA BE LIABLE FOR ANY
+         * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+         * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+         * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
+         * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+         * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+         * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+         */
+
+        switch (className.toLowerCase()) {
+
+            case "statement":
+                if (node.type.slice(-9) === "Statement") {
+                    return true;
+                }
+
+                // fallthrough: interface Declaration <: Statement { }
+
+            case "declaration":
+                return node.type.slice(-11) === "Declaration";
+
+            case "pattern":
+                if (node.type.slice(-7) === "Pattern") {
+                    return true;
+                }
+
+                // fallthrough: interface Expression <: Node, Pattern { }
+
+            case "expression":
+                return node.type.slice(-10) === "Expression" ||
+                    node.type.slice(-7) === "Literal" ||
+                    (
+                        node.type === "Identifier" &&
+                        (ancestry.length === 0 || ancestry[0].type !== "MetaProperty")
+                    ) ||
+                    node.type === "MetaProperty";
+
+            case "function":
+                return node.type === "FunctionDeclaration" ||
+                    node.type === "FunctionExpression" ||
+                    node.type === "ArrowFunctionExpression";
+
+            default:
+                throw new Error(`Unknown class name: ${className}`);
+        }
+    },
+
+    /**
+     * Parses the given file into an AST.
+     * @param {VFile} file The virtual file to parse.
+     * @param {Object} options Additional options passed from ESLint.
+     * @param {LanguageOptions} options.languageOptions The language options.
+     * @returns {Object} The result of parsing.
+     */
+    parse(file, { languageOptions }) {
+
+        // Note: BOM already removed
+        const { body: text, path: filePath } = file;
+        const textToParse = text.replace(astUtils.shebangPattern, (match, captured) => `//${captured}`);
+        const { ecmaVersion, sourceType, parser } = languageOptions;
+        const parserOptions = Object.assign(
+            { ecmaVersion, sourceType },
+            languageOptions.parserOptions,
+            {
+                loc: true,
+                range: true,
+                raw: true,
+                tokens: true,
+                comment: true,
+                eslintVisitorKeys: true,
+                eslintScopeManager: true,
+                filePath
+            }
+        );
+
+        /*
+         * Check for parsing errors first. If there's a parsing error, nothing
+         * else can happen. However, a parsing error does not throw an error
+         * from this method - it's just considered a fatal error message, a
+         * problem that ESLint identified just like any other.
+         */
+        try {
+            debug("Parsing:", filePath);
+            const parseResult = (typeof parser.parseForESLint === "function")
+                ? parser.parseForESLint(textToParse, parserOptions)
+                : { ast: parser.parse(textToParse, parserOptions) };
+
+            debug("Parsing successful:", filePath);
+
+            const {
+                ast,
+                services: parserServices = {},
+                visitorKeys = evk.KEYS,
+                scopeManager
+            } = parseResult;
+
+            return {
+                ok: true,
+                ast,
+                parserServices,
+                visitorKeys,
+                scopeManager
+            };
+        } catch (ex) {
+
+            // 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 {
+                ok: false,
+                errors: [{
+                    message,
+                    line: ex.lineNumber,
+                    column: ex.column
+                }]
+            };
+        }
+
+    },
+
+    /**
+     * Creates a new `SourceCode` object from the given information.
+     * @param {VFile} file The virtual file to create a `SourceCode` object from.
+     * @param {Object} parseResult The result returned from `parse()`.
+     * @param {Object} options Additional options passed from ESLint.
+     * @param {LanguageOptions} options.languageOptions The language options.
+     * @returns {SourceCode} The new `SourceCode` object.
+     */
+    createSourceCode(file, parseResult, { languageOptions }) {
+
+        const { body: text, path: filePath, bom: hasBOM } = file;
+        const { ast, parserServices, visitorKeys } = parseResult;
+
+        debug("Scope analysis:", filePath);
+        const scopeManager = parseResult.scopeManager || analyzeScope(ast, languageOptions, visitorKeys);
+
+        debug("Scope analysis successful:", filePath);
+
+        return new SourceCode({
+            text,
+            ast,
+            hasBOM,
+            parserServices,
+            scopeManager,
+            visitorKeys
+        });
+    }
+
+};

package/lib/{source-code → languages/js/source-code}/source-code.js

@@ -11,18 +11,16 @@
 const
     { isCommentToken } = require("@eslint-community/eslint-utils"),
     TokenStore = require("./token-store"),
-    astUtils = require("../shared/ast-utils"),
-    Traverser = require("../shared/traverser"),
-    globals = require("../../conf/globals"),
+    astUtils = require("../../../shared/ast-utils"),
+    Traverser = require("../../../shared/traverser"),
+    globals = require("../../../../conf/globals"),
     {
         directivesPattern
-    } = require("../shared/directives"),
+    } = require("../../../shared/directives"),
 
-    /* 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. */
+    CodePathAnalyzer = require("../../../linter/code-path-analysis/code-path-analyzer"),
+    createEmitter = require("../../../linter/safe-emitter"),
+    ConfigCommentParser = require("../../../linter/config-comment-parser"),
 
     eslintScope = require("eslint-scope");
 
@@ -441,24 +439,28 @@ class SourceCode extends TokenStore {
     #steps;
 
     /**
+     * Creates a new instance.
      * @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.
+     * @param {boolean} textOrConfig.hasBOM Indicates if the text has a Unicode BOM.
      * @param {Object|null} textOrConfig.parserServices The parser services.
      * @param {ScopeManager|null} textOrConfig.scopeManager The scope of this source code.
      * @param {Object|null} textOrConfig.visitorKeys The visitor keys to traverse AST.
      * @param {ASTNode} [astIfNoConfig] The Program node of the AST representing the code. This AST should be created from the text that BOM was stripped.
      */
     constructor(textOrConfig, astIfNoConfig) {
-        let text, ast, parserServices, scopeManager, visitorKeys;
+        let text, hasBOM, ast, parserServices, scopeManager, visitorKeys;
 
-        // Process overloading.
+        // Process overloading of arguments
         if (typeof textOrConfig === "string") {
             text = textOrConfig;
             ast = astIfNoConfig;
+            hasBOM = false;
         } else if (typeof textOrConfig === "object" && textOrConfig !== null) {
             text = textOrConfig.text;
             ast = textOrConfig.ast;
+            hasBOM = textOrConfig.hasBOM;
             parserServices = textOrConfig.parserServices;
             scopeManager = textOrConfig.scopeManager;
             visitorKeys = textOrConfig.visitorKeys;
@@ -476,18 +478,39 @@ class SourceCode extends TokenStore {
             ["configNodes", void 0]
         ]);
 
+        /**
+         * Indicates if the AST is ESTree compatible.
+         * @type {boolean}
+         */
+        this.isESTree = ast.type === "Program";
+
+        /*
+         * Backwards compatibility for BOM handling.
+         *
+         * The `hasBOM` property has been available on the `SourceCode` object
+         * for a long time and is used to indicate if the source contains a BOM.
+         * The linter strips the BOM and just passes the `hasBOM` property to the
+         * `SourceCode` constructor to make it easier for languages to not deal with
+         * the BOM.
+         *
+         * However, the text passed in to the `SourceCode` constructor might still
+         * have a BOM if the constructor is called outside of the linter, so we still
+         * need to check for the BOM in the text.
+         */
+        const textHasBOM = text.charCodeAt(0) === 0xFEFF;
+
         /**
          * The flag to indicate that the source code has Unicode BOM.
          * @type {boolean}
          */
-        this.hasBOM = (text.charCodeAt(0) === 0xFEFF);
+        this.hasBOM = textHasBOM || !!hasBOM;
 
         /**
          * The original text source code.
          * BOM was stripped from this text.
          * @type {string}
          */
-        this.text = (this.hasBOM ? text.slice(1) : text);
+        this.text = (textHasBOM ? text.slice(1) : text);
 
         /**
          * The parsed AST for the source code.
@@ -1164,12 +1187,11 @@ class SourceCode extends TokenStore {
      */
     finalize() {
 
-        // Step 1: ensure that all of the necessary variables are up to date
         const varsCache = this[caches].get("vars");
-        const globalScope = this.scopeManager.scopes[0];
         const configGlobals = varsCache.get("configGlobals");
         const inlineGlobals = varsCache.get("inlineGlobals");
         const exportedVariables = varsCache.get("exportedVariables");
+        const globalScope = this.scopeManager.scopes[0];
 
         addDeclaredGlobals(globalScope, configGlobals, inlineGlobals);
 
@@ -1227,9 +1249,7 @@ class SourceCode extends TokenStore {
          * 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) {
+        if (this.isESTree) {
             analyzer = new CodePathAnalyzer(analyzer);
 
             CODE_PATH_EVENTS.forEach(eventName => {

package/lib/languages/js/validate-language-options.js

@@ -0,0 +1,181 @@
+/**
+ * @fileoverview The schema to validate language options
+ * @author Nicholas C. Zakas
+ */
+
+"use strict";
+
+//-----------------------------------------------------------------------------
+// Data
+//-----------------------------------------------------------------------------
+
+const globalVariablesValues = new Set([
+    true, "true", "writable", "writeable",
+    false, "false", "readonly", "readable", null,
+    "off"
+]);
+
+//------------------------------------------------------------------------------
+// Helpers
+//------------------------------------------------------------------------------
+
+/**
+ * Check if a value is a non-null object.
+ * @param {any} value The value to check.
+ * @returns {boolean} `true` if the value is a non-null object.
+ */
+function isNonNullObject(value) {
+    return typeof value === "object" && value !== null;
+}
+
+/**
+ * Check if a value is a non-null non-array object.
+ * @param {any} value The value to check.
+ * @returns {boolean} `true` if the value is a non-null non-array object.
+ */
+function isNonArrayObject(value) {
+    return isNonNullObject(value) && !Array.isArray(value);
+}
+
+/**
+ * Check if a value is undefined.
+ * @param {any} value The value to check.
+ * @returns {boolean} `true` if the value is undefined.
+ */
+function isUndefined(value) {
+    return typeof value === "undefined";
+}
+
+//-----------------------------------------------------------------------------
+// Schemas
+//-----------------------------------------------------------------------------
+
+/**
+ * Validates the ecmaVersion property.
+ * @param {string|number} ecmaVersion The value to check.
+ * @returns {void}
+ * @throws {TypeError} If the value is invalid.
+ */
+function validateEcmaVersion(ecmaVersion) {
+
+    if (isUndefined(ecmaVersion)) {
+        throw new TypeError("Key \"ecmaVersion\": Expected an \"ecmaVersion\" property.");
+    }
+
+    if (typeof ecmaVersion !== "number" && ecmaVersion !== "latest") {
+        throw new TypeError("Key \"ecmaVersion\": Expected a number or \"latest\".");
+    }
+
+}
+
+/**
+ * Validates the sourceType property.
+ * @param {string} sourceType The value to check.
+ * @returns {void}
+ * @throws {TypeError} If the value is invalid.
+ */
+function validateSourceType(sourceType) {
+
+    if (typeof sourceType !== "string" || !/^(?:script|module|commonjs)$/u.test(sourceType)) {
+        throw new TypeError("Key \"sourceType\": Expected \"script\", \"module\", or \"commonjs\".");
+    }
+
+}
+
+/**
+ * Validates the globals property.
+ * @param {Object} globals The value to check.
+ * @returns {void}
+ * @throws {TypeError} If the value is invalid.
+ */
+function validateGlobals(globals) {
+
+    if (!isNonArrayObject(globals)) {
+        throw new TypeError("Key \"globals\": Expected an object.");
+    }
+
+    for (const key of Object.keys(globals)) {
+
+        // avoid hairy edge case
+        if (key === "__proto__") {
+            continue;
+        }
+
+        if (key !== key.trim()) {
+            throw new TypeError(`Key "globals": Global "${key}" has leading or trailing whitespace.`);
+        }
+
+        if (!globalVariablesValues.has(globals[key])) {
+            throw new TypeError(`Key "globals": Key "${key}": Expected "readonly", "writable", or "off".`);
+        }
+    }
+}
+
+/**
+ * Validates the parser property.
+ * @param {Object} parser The value to check.
+ * @returns {void}
+ * @throws {TypeError} If the value is invalid.
+ */
+function validateParser(parser) {
+
+    if (!parser || typeof parser !== "object" ||
+        (typeof parser.parse !== "function" && typeof parser.parseForESLint !== "function")
+    ) {
+        throw new TypeError("Key \"parser\": Expected object with parse() or parseForESLint() method.");
+    }
+
+}
+
+/**
+ * Validates the language options.
+ * @param {Object} languageOptions The language options to validate.
+ * @returns {void}
+ * @throws {TypeError} If the language options are invalid.
+ */
+function validateLanguageOptions(languageOptions) {
+
+    if (!isNonArrayObject(languageOptions)) {
+        throw new TypeError("Expected an object.");
+    }
+
+    const {
+        ecmaVersion,
+        sourceType,
+        globals,
+        parser,
+        parserOptions,
+        ...otherOptions
+    } = languageOptions;
+
+    if ("ecmaVersion" in languageOptions) {
+        validateEcmaVersion(ecmaVersion);
+    }
+
+    if ("sourceType" in languageOptions) {
+        validateSourceType(sourceType);
+    }
+
+    if ("globals" in languageOptions) {
+        validateGlobals(globals);
+    }
+
+    if ("parser" in languageOptions) {
+        validateParser(parser);
+    }
+
+    if ("parserOptions" in languageOptions) {
+        if (!isNonArrayObject(parserOptions)) {
+            throw new TypeError("Key \"parserOptions\": Expected an object.");
+        }
+    }
+
+    const otherOptionKeys = Object.keys(otherOptions);
+
+    if (otherOptionKeys.length > 0) {
+        throw new TypeError(`Unexpected key "${otherOptionKeys[0]}" found.`);
+    }
+
+}
+
+module.exports = { validateLanguageOptions };

package/lib/linter/apply-disable-directives.js

@@ -369,6 +369,8 @@ function applyDirectives(options) {
 
     const processed = processUnusedDirectives(unusedDisableDirectivesToReport)
         .concat(processUnusedDirectives(unusedEnableDirectivesToReport));
+    const columnOffset = options.language.columnStart === 1 ? 0 : 1;
+    const lineOffset = options.language.lineStart === 1 ? 0 : 1;
 
     const unusedDirectives = processed
         .map(({ description, fix, unprocessedDirective }) => {
@@ -388,8 +390,8 @@ function applyDirectives(options) {
             return {
                 ruleId: null,
                 message,
-                line: type === "disable-next-line" ? parentDirective.node.loc.start.line : line,
-                column: type === "disable-next-line" ? parentDirective.node.loc.start.column + 1 : column,
+                line: type === "disable-next-line" ? parentDirective.node.loc.start.line + lineOffset : line,
+                column: type === "disable-next-line" ? parentDirective.node.loc.start.column + columnOffset : column,
                 severity: options.reportUnusedDisableDirectives === "warn" ? 1 : 2,
                 nodeType: null,
                 ...options.disableFixes ? {} : { fix }
@@ -403,6 +405,7 @@ function applyDirectives(options) {
  * Given a list of directive comments (i.e. metadata about eslint-disable and eslint-enable comments) and a list
  * of reported problems, adds the suppression information to the problems.
  * @param {Object} options Information about directives and problems
+ * @param {Language} options.language The language being linted.
  * @param {{
  *      type: ("disable"|"enable"|"disable-line"|"disable-next-line"),
  *      ruleId: (string|null),
@@ -421,7 +424,7 @@ function applyDirectives(options) {
  * @returns {{ruleId: (string|null), line: number, column: number, suppressions?: {kind: string, justification: string}}[]}
  * An object with a list of reported problems, the suppressed of which contain the suppression information.
  */
-module.exports = ({ directives, disableFixes, problems, configuredRules, ruleFilter, reportUnusedDisableDirectives = "off" }) => {
+module.exports = ({ language, directives, disableFixes, problems, configuredRules, ruleFilter, reportUnusedDisableDirectives = "off" }) => {
     const blockDirectives = directives
         .filter(directive => directive.type === "disable" || directive.type === "enable")
         .map(directive => Object.assign({}, directive, { unprocessedDirective: directive }))
@@ -470,6 +473,7 @@ module.exports = ({ directives, disableFixes, problems, configuredRules, ruleFil
     }
 
     const blockDirectivesResult = applyDirectives({
+        language,
         problems,
         directives: blockDirectives,
         disableFixes,
@@ -477,6 +481,7 @@ module.exports = ({ directives, disableFixes, problems, configuredRules, ruleFil
         rulesToIgnore
     });
     const lineDirectivesResult = applyDirectives({
+        language,
         problems: blockDirectivesResult.problems,
         directives: lineDirectives,
         disableFixes,