feat!: Use ScopeManager#addGlobals() (#20132)

mdjermanovic · fasttime · web-flow · commit 208b5cc34a83 · 2025-11-12T13:21:28.000+01:00
* feat!: Use `ScopeManager#addGlobals()`

* patch `@typescript-eslint/parser`

* update tests

* fix knip errors

* fix behavior with `--no-inline-config`

* add more tests

* add more tests

* cleanup tests for predefined globals

* add more test assertions

* update types and docs

* disable `eslint-webpack-plugin` types integration test in CI

* update scope-manager-interface.md

* fix tests

* Update lib/languages/js/source-code/source-code.js

Co-authored-by: Francesco Trotta &lt;github@fasttime.org&gt;

* use main branch of eslint/js

* update migration guide

* update dependencies

---------

Co-authored-by: Francesco Trotta &lt;github@fasttime.org&gt;
diff --git a/.github/workflows/types-integration.yml b/.github/workflows/types-integration.yml
@@ -10,6 +10,7 @@ permissions:
 
 jobs:
     webpack_plugin:
+        if: false # Temporarily disabled until @typescript-eslint/parser is updated
         name: Types (eslint-webpack-plugin)
         runs-on: ubuntu-latest
         steps:
diff --git a/docs/package.json b/docs/package.json
@@ -31,7 +31,7 @@
         "@11ty/eleventy-plugin-syntaxhighlight": "^5.0.0",
         "@munter/tap-render": "^0.2.0",
         "@types/markdown-it": "^12.2.3",
-        "@typescript-eslint/parser": "^8.27.0",
+        "@typescript-eslint/parser": "file:../tools/typescript-eslint-parser",
         "algoliasearch": "^4.12.1",
         "autoprefixer": "^10.4.13",
         "cross-env": "^7.0.3",
diff --git a/docs/src/extend/custom-parsers.md b/docs/src/extend/custom-parsers.md
@@ -48,6 +48,7 @@ The `parseForESLint` method should return an object that contains the required p
 - `services` can contain any parser-dependent services (such as type checkers for nodes). The value of the `services` property is available to rules as `context.sourceCode.parserServices`. Default is an empty object.
 - `scopeManager` can be a [ScopeManager](./scope-manager-interface) object. Custom parsers can use customized scope analysis for experimental/enhancement syntaxes. The default is the `ScopeManager` object which is created by [eslint-scope](https://github.com/eslint/js/tree/main/packages/eslint-scope).
     - Support for `scopeManager` was added in ESLint v4.14.0. ESLint versions that support `scopeManager` will provide an `eslintScopeManager: true` property in `parserOptions`, which can be used for feature detection.
+    - As of ESLint v10.0.0, `ScopeManager` must automatically resolve references to global variables declared in the code, and provide an instance method `addGlobals(names: string[])` that creates variables with the given names in the global scope and resolves references to them.
 - `visitorKeys` can be an object to customize AST traversal. The keys of the object are the type of AST nodes. Each value is an array of the property names which should be traversed. The default is [KEYS of `eslint-visitor-keys`](https://github.com/eslint/js/tree/main/packages/eslint-visitor-keys#evkkeys).
     - Support for `visitorKeys` was added in ESLint v4.14.0. ESLint versions that support `visitorKeys` will provide an `eslintVisitorKeys: true` property in `parserOptions`, which can be used for feature detection.
 
diff --git a/docs/src/extend/scope-manager-interface.md b/docs/src/extend/scope-manager-interface.md
@@ -32,6 +32,13 @@ This document was written based on the implementation of [eslint-scope](https://
 - **Return type:** `Scope | null`
 - **Description:** Get the scope of a given AST node. The gotten scope's `block` property is the node. This method never returns `function-expression-name` scope. If the node does not have their scope, this returns `null`.
 
+#### addGlobals(names)
+
+- **Parameters:**
+    - `names` (`string[]`) ... Names of variables to add to the global scope.
+- **Return type:** `undefined`
+- **Description:** Adds variables to the global scope and resolves references to them. This method is used by the ESLint core and should never be used in rules.
+
 #### getDeclaredVariables(node)
 
 - **Parameters:**
diff --git a/docs/src/use/migrate-to-10.0.0.md b/docs/src/use/migrate-to-10.0.0.md
@@ -31,6 +31,7 @@ The lists below are ordered roughly by the number of users each change is expect
 - [Removal of `type` property in errors of invalid `RuleTester` cases](#ruletester-type-removed)
 - [Fixer methods now require string `text` arguments](#fixer-text-must-be-string)
 - [`Program` AST node range spans entire source text](#program-node-range)
+- [New requirements for `ScopeManager` implementations](#scope-manager)
 
 ### Breaking changes for integration developers
 
@@ -176,6 +177,18 @@ Starting with ESLint v10, `Program.range` covers the entire source text, includi
 
 **Related issue(s):** [eslint/js#648](https://github.com/eslint/js/issues/648)
 
+## <a name="scope-manager"></a> New requirements for `ScopeManager` implementations
+
+As of ESLint v10.0.0, custom `ScopeManager` implementations must automatically resolve references to global variables declared in the code, including `var` and `function` declarations, and provide an instance method `addGlobals(names: string[])` that creates variables with the given names in the global scope and resolves references to them.
+
+The default `ScopeManager` implementation [`eslint-scope`](https://www.npmjs.com/package/eslint-scope) has already been updated.
+
+This change does not affect custom rules.
+
+**To address:** If you maintain a custom parser that provides a custom `ScopeManager` implementation, update your custom `ScopeManager` implementation.
+
+**Related issue(s):** [eslint/js#665](https://github.com/eslint/js/issues/665)
+
 ## <a name="eslint-env-comments"></a> `eslint-env` comments are reported as errors
 
 In the now obsolete ESLint v8 configuration system, `/* eslint-env */` comments could be used to define globals for a file. The current configuration system does not support such comments, and starting with ESLint v10, they are reported as errors during linting.
diff --git a/knip.jsonc b/knip.jsonc
@@ -41,6 +41,6 @@
       "ignore": ["tests/types/**"],
       "ignoreDependencies": ["eslint"],
     },
-    "tools/internal-rules": {},
+    "tools/typescript-eslint-parser": {},
   },
 }
diff --git a/lib/languages/js/source-code/source-code.js b/lib/languages/js/source-code/source-code.js
@@ -20,15 +20,15 @@ const { isCommentToken } = require("@eslint-community/eslint-utils"),
 		VisitNodeStep,
 		CallMethodStep,
 		Directive,
-	} = require("@eslint/plugin-kit"),
-	eslintScope = require("eslint-scope");
+	} = require("@eslint/plugin-kit");
 
 //------------------------------------------------------------------------------
 // Type Definitions
 //------------------------------------------------------------------------------
 
 /** @typedef {import("eslint-scope").Variable} Variable */
 /** @typedef {import("eslint-scope").Scope} Scope */
+/** @typedef {import("eslint-scope").ScopeManager} ScopeManager */
 /** @typedef {import("@eslint/core").SourceCode} ISourceCode */
 /** @typedef {import("@eslint/core").Directive} IDirective */
 /** @typedef {import("@eslint/core").TraversalStep} ITraversalStep */
@@ -264,103 +264,37 @@ function findLineNumberBinarySearch(lineStartIndices, target) {
  * Ensures that variables representing built-in properties of the Global Object,
  * and any globals declared by special block comments, are present in the global
  * scope.
- * @param {Scope} globalScope The global scope.
+ * @param {ScopeManager} scopeManager Scope manager.
  * @param {Object|undefined} configGlobals The globals declared in configuration
  * @param {Object|undefined} inlineGlobals The globals declared in the source code
  * @returns {void}
  */
 function addDeclaredGlobals(
-	globalScope,
-	configGlobals = {},
-	inlineGlobals = {},
+	scopeManager,
+	configGlobals = Object.create(null),
+	inlineGlobals = Object.create(null),
 ) {
-	// Define configured global variables.
-	for (const id of new Set([
-		...Object.keys(configGlobals),
-		...Object.keys(inlineGlobals),
-	])) {
-		/*
-		 * `normalizeConfigGlobal` will throw an error if a configured global value is invalid. However, these errors would
-		 * typically be caught when validating a config anyway (validity for inline global comments is checked separately).
-		 */
-		const configValue =
-			configGlobals[id] === void 0
-				? void 0
-				: normalizeConfigGlobal(configGlobals[id]);
-		const commentValue = inlineGlobals[id] && inlineGlobals[id].value;
-		const value = commentValue || configValue;
-		const sourceComments = inlineGlobals[id] && inlineGlobals[id].comments;
-
-		if (value === "off") {
-			continue;
-		}
-
-		let variable = globalScope.set.get(id);
-
-		if (!variable) {
-			variable = new eslintScope.Variable(id, globalScope);
-
-			globalScope.variables.push(variable);
-			globalScope.set.set(id, variable);
-		}
+	const finalGlobals = { __proto__: null, ...configGlobals };
 
-		variable.eslintImplicitGlobalSetting = configValue;
-		variable.eslintExplicitGlobal = sourceComments !== void 0;
-		variable.eslintExplicitGlobalComments = sourceComments;
-		variable.writeable = value === "writable";
+	for (const [name, data] of Object.entries(inlineGlobals)) {
+		finalGlobals[name] = data.value;
 	}
 
-	/*
-	 * "through" contains all references which definitions cannot be found.
-	 * Since we augment the global scope using configuration, we need to update
-	 * references and remove the ones that were added by configuration.
-	 */
-	globalScope.through = globalScope.through.filter(reference => {
-		const name = reference.identifier.name;
-		const variable = globalScope.set.get(name);
-
-		if (variable) {
-			/*
-			 * Links the variable and the reference.
-			 * And this reference is removed from `Scope#through`.
-			 */
-			reference.resolved = variable;
-			variable.references.push(reference);
+	const names = Object.keys(finalGlobals).filter(
+		name => finalGlobals[name] !== "off",
+	);
 
-			return false;
-		}
+	scopeManager.addGlobals(names);
 
-		return true;
-	});
+	const globalScope = scopeManager.scopes[0];
 
-	/*
-	 * "implicit" contains information about implicit global variables (those created
-	 * implicitly by assigning values to undeclared variables in non-strict code).
-	 * Since we augment the global scope using configuration, we need to remove
-	 * the ones that were added by configuration, as they are either built-in
-	 * or declared elsewhere, therefore not implicit.
-	 * Since the "implicit" property was not documented, first we'll check if it exists
-	 * because it's possible that not all custom scope managers create this property.
-	 * If it exists, we assume it has properties `variables` and `set`. Property
-	 * `left` is considered optional (for example, typescript-eslint's scope manage
-	 * has this property named `leftToBeResolved`).
-	 */
-	const { implicit } = globalScope;
-	if (typeof implicit === "object" && implicit !== null) {
-		implicit.variables = implicit.variables.filter(variable => {
-			const name = variable.name;
-			if (globalScope.set.has(name)) {
-				implicit.set.delete(name);
-				return false;
-			}
-			return true;
-		});
+	for (const name of names) {
+		const variable = globalScope.set.get(name);
 
-		if (implicit.left) {
-			implicit.left = implicit.left.filter(
-				reference => !globalScope.set.has(reference.identifier.name),
-			);
-		}
+		variable.eslintImplicitGlobalSetting = configGlobals[name];
+		variable.eslintExplicitGlobal = !!inlineGlobals[name];
+		variable.eslintExplicitGlobalComments = inlineGlobals[name]?.comments;
+		variable.writeable = finalGlobals[name] === "writable";
 	}
 }
 
@@ -1162,6 +1096,15 @@ class SourceCode extends TokenStore {
 				: void 0,
 			languageOptions.globals,
 		);
+
+		/*
+		 * `normalizeConfigGlobal` will throw an error if a configured global value is invalid. However, these errors would
+		 * typically be caught when validating a config anyway (validity for inline global comments is checked separately).
+		 */
+		for (const [name, value] of Object.entries(configGlobals)) {
+			configGlobals[name] = normalizeConfigGlobal(value);
+		}
+
 		const varsCache = this[caches].get("vars");
 
 		varsCache.set("configGlobals", configGlobals);
@@ -1282,7 +1225,7 @@ class SourceCode extends TokenStore {
 		const exportedVariables = varsCache.get("exportedVariables");
 		const globalScope = this.scopeManager.scopes[0];
 
-		addDeclaredGlobals(globalScope, configGlobals, inlineGlobals);
+		addDeclaredGlobals(this.scopeManager, configGlobals, inlineGlobals);
 
 		if (exportedVariables) {
 			markExportedVariables(globalScope, exportedVariables);
diff --git a/lib/types/index.d.ts b/lib/types/index.d.ts
@@ -134,6 +134,8 @@ export namespace Scope {
 		acquire(node: ESTree.Node, inner?: boolean): Scope | null;
 
 		getDeclaredVariables(node: ESTree.Node): Variable[];
+
+		addGlobals(names: string[]): void;
 	}
 
 	interface Scope {
diff --git a/package.json b/package.json
@@ -123,8 +123,8 @@
     "cross-spawn": "^7.0.6",
     "debug": "^4.3.2",
     "escape-string-regexp": "^4.0.0",
-    "eslint-scope": "^8.4.0",
-    "eslint-visitor-keys": "^4.2.1",
+    "eslint-scope": "^9.0.0",
+    "eslint-visitor-keys": "^5.0.0",
     "espree": "^11.0.0",
     "esquery": "^1.5.0",
     "esutils": "^2.0.2",
@@ -150,7 +150,7 @@
     "@trunkio/launcher": "^1.3.4",
     "@types/esquery": "^1.5.4",
     "@types/node": "^22.13.14",
-    "@typescript-eslint/parser": "^8.4.0",
+    "@typescript-eslint/parser": "file:tools/typescript-eslint-parser",
     "babel-loader": "^8.0.5",
     "c8": "^7.12.0",
     "chai": "^4.0.1",
diff --git a/tests/fixtures/parsers/non-js-parser.js b/tests/fixtures/parsers/non-js-parser.js
@@ -225,7 +225,17 @@ exports.parseForESLint = () => ({
         "range": {}
     },
     services: {},
-    scopeManager: { variables: [], scopes: [{ set: new Map(), variables: [], through: [] }], getDeclaredVariables: () => {} },
+    scopeManager: {
+		variables: [],
+		scopes: [{ set: new Map(), variables: [], through: [] }],
+		getDeclaredVariables() {},
+		addGlobals(names) {
+			const globalScope = this.scopes[0];
+			for (const name of names) {
+				globalScope.set.set(name, {});
+			}
+		}
+	},
     visitorKeys: {
         Document: ['definitions'],
         ObjectTypeDefinition: ['interfaces', 'directives', 'fields'],
diff --git a/tests/lib/languages/js/source-code/source-code.js b/tests/lib/languages/js/source-code/source-code.js
diff --git a/tests/lib/types/types.test.ts b/tests/lib/types/types.test.ts
diff --git a/tools/typescript-eslint-parser/index.js b/tools/typescript-eslint-parser/index.js
diff --git a/tools/typescript-eslint-parser/package.json b/tools/typescript-eslint-parser/package.json

Original file line number	Diff line number	Diff line change
`@@ -41,6 +41,6 @@`
`41`	`41`	`"ignore": ["tests/types/**"],`
`42`	`42`	`"ignoreDependencies": ["eslint"],`
`43`	`43`	`},`
`44`		`- "tools/internal-rules": {},`
	`44`	`+ "tools/typescript-eslint-parser": {},`
`45`	`45`	`},`
`46`	`46`	`}`
Original file line number	Diff line number	Diff line change
`@@ -134,6 +134,8 @@ export namespace Scope {`
`134`	`134`	`acquire(node: ESTree.Node, inner?: boolean): Scope \| null;`
`135`	`135`
`136`	`136`	`getDeclaredVariables(node: ESTree.Node): Variable[];`
	`137`	`+`
	`138`	`+ addGlobals(names: string[]): void;`
`137`	`139`	`}`
`138`	`140`
`139`	`141`	`interface Scope {`