feat: add reportGlobalThis to no-shadow-restricted-names (#19670)

sethamus · web-flow · commit e9754e7433ed · 2025-05-02T22:31:46.000+02:00
* feat: add reportGlobalThis to no-shadow-restricted-names

* fix CI

* add tests

* add test
diff --git a/docs/src/_data/further_reading_links.json b/docs/src/_data/further_reading_links.json
@@ -782,5 +782,19 @@
     "logo": "https://wiki.sei.cmu.edu/confluence/s/-ctumb3/9012/tu5x00/7/_/favicon.ico",
     "title": "MSC56-J. Detect and remove superfluous code and values - SEI CERT Oracle Coding Standard for Java - Confluence",
     "description": null
+  },
+  "https://262.ecma-international.org/11.0/#sec-value-properties-of-the-global-object": {
+    "domain": "262.ecma-international.org",
+    "url": "https://262.ecma-international.org/11.0/#sec-value-properties-of-the-global-object",
+    "logo": "https://tc39.es/ecma262/2020/img/favicon.ico",
+    "title": "ECMAScript® 2020 Language Specification",
+    "description": null
+  },
+  "https://262.ecma-international.org/11.0/#sec-strict-mode-of-ecmascript": {
+    "domain": "262.ecma-international.org",
+    "url": "https://262.ecma-international.org/11.0/#sec-strict-mode-of-ecmascript",
+    "logo": "https://tc39.es/ecma262/2020/img/favicon.ico",
+    "title": "ECMAScript® 2020 Language Specification",
+    "description": null
   }
 }
diff --git a/docs/src/rules/no-shadow-restricted-names.md b/docs/src/rules/no-shadow-restricted-names.md
@@ -4,13 +4,13 @@ rule_type: suggestion
 related_rules:
 - no-shadow
 further_reading:
-- https://es5.github.io/#x15.1.1
-- https://es5.github.io/#C
+- https://262.ecma-international.org/11.0/#sec-value-properties-of-the-global-object
+- https://262.ecma-international.org/11.0/#sec-strict-mode-of-ecmascript
 ---
 
 
 
-ES5 §15.1.1 Value Properties of the Global Object (`NaN`, `Infinity`, `undefined`) as well as strict mode restricted identifiers `eval` and `arguments` are considered to be restricted names in JavaScript. Defining them to mean something else can have unintended consequences and confuse others reading the code. For example, there's nothing preventing you from writing:
+ES2020 §18.1 Value Properties of the Global Object (`globalThis`, `NaN`, `Infinity`, `undefined`) as well as strict mode restricted identifiers `eval` and `arguments` are considered to be restricted names in JavaScript. Defining them to mean something else can have unintended consequences and confuse others reading the code. For example, there's nothing preventing you from writing:
 
 ```js
 const undefined = "foo";
@@ -78,3 +78,71 @@ import { undefined as undef } from "bar";
 ```
 
 :::
+
+## Options
+
+This rule has an object option:
+
+* `"reportGlobalThis"`: `true` (default `false`) reports declarations of `globalThis`.
+
+### reportGlobalThis
+
+Examples of **incorrect** code for the `{ "reportGlobalThis": true }` option:
+
+::: incorrect
+
+```js
+/*eslint no-shadow-restricted-names: ["error", { "reportGlobalThis": true }]*/
+
+const globalThis = "foo";
+```
+
+:::
+
+::: incorrect
+
+```js
+/*eslint no-shadow-restricted-names: ["error", { "reportGlobalThis": true }]*/
+
+function globalThis() {}
+```
+
+:::
+
+::: incorrect
+
+```js
+/*eslint no-shadow-restricted-names: ["error", { "reportGlobalThis": true }]*/
+
+import { globalThis } from "bar";
+```
+
+:::
+
+::: incorrect
+
+```js
+/*eslint no-shadow-restricted-names: ["error", { "reportGlobalThis": true }]*/
+
+class globalThis {}
+```
+
+:::
+
+Examples of **correct** code for the `{ "reportGlobalThis": true }` option:
+
+::: correct
+
+```js
+/*eslint no-shadow-restricted-names: ["error", { "reportGlobalThis": true }]*/
+
+const foo = globalThis;
+
+function bar() {
+    return globalThis;
+}
+
+import { globalThis as baz } from "foo";
+```
+
+:::
diff --git a/lib/rules/no-shadow-restricted-names.js b/lib/rules/no-shadow-restricted-names.js
@@ -1,5 +1,5 @@
 /**
- * @fileoverview Disallow shadowing of NaN, undefined, and Infinity (ES5 section 15.1.1)
+ * @fileoverview Disallow shadowing of globalThis, NaN, undefined, and Infinity (ES2020 section 18.1)
  * @author Michael Ficarra
  */
 "use strict";
@@ -32,27 +32,50 @@ module.exports = {
 	meta: {
 		type: "suggestion",
 
+		defaultOptions: [
+			{
+				reportGlobalThis: false,
+			},
+		],
+
 		docs: {
 			description: "Disallow identifiers from shadowing restricted names",
 			recommended: true,
 			url: "https://eslint.org/docs/latest/rules/no-shadow-restricted-names",
 		},
 
-		schema: [],
+		schema: [
+			{
+				type: "object",
+				properties: {
+					reportGlobalThis: {
+						type: "boolean",
+					},
+				},
+				additionalProperties: false,
+			},
+		],
 
 		messages: {
 			shadowingRestrictedName: "Shadowing of global property '{{name}}'.",
 		},
 	},
 
 	create(context) {
+		const [{ reportGlobalThis }] = context.options;
+
 		const RESTRICTED = new Set([
 			"undefined",
 			"NaN",
 			"Infinity",
 			"arguments",
 			"eval",
 		]);
+
+		if (reportGlobalThis) {
+			RESTRICTED.add("globalThis");
+		}
+
 		const sourceCode = context.sourceCode;
 
 		// Track reported nodes to avoid duplicate reports. For example, on class declarations.
diff --git a/lib/types/rules.d.ts b/lib/types/rules.d.ts
@@ -3578,7 +3578,16 @@ export interface ESLintRules extends Linter.RulesRecord {
 	 * @since 0.1.4
 	 * @see https://eslint.org/docs/latest/rules/no-shadow-restricted-names
 	 */
-	"no-shadow-restricted-names": Linter.RuleEntry<[]>;
+	"no-shadow-restricted-names": Linter.RuleEntry<
+		[
+			Partial<{
+				/**
+				 * @default false
+				 */
+				reportGlobalThis: boolean;
+			}>,
+		]
+	>;
 
 	/**
 	 * Rule to disallow spacing between function identifiers and their applications (deprecated).
diff --git a/tests/lib/rules/no-shadow-restricted-names.js b/tests/lib/rules/no-shadow-restricted-names.js
