feat: add ignoreDirectives option in no-unused-expressions (#19645)

sethamus · web-flow · commit 2dfd83ef4ee0 · 2025-04-24T19:31:29.000+05:30
diff --git a/docs/src/rules/no-unused-expressions.md b/docs/src/rules/no-unused-expressions.md
@@ -24,7 +24,7 @@ function Thing() { nThings += 1; }
 new Thing(); // constructed object is unused, but nThings changed as a side effect
 ```
 
-This rule does not apply to directives (which are in the form of literal string expressions such as `"use strict";` at the beginning of a script, module, or function).
+This rule does not apply to directives (which are in the form of literal string expressions such as `"use strict";` at the beginning of a script, module, or function) when using ES5+ environments. In ES3 environments, directives are treated as unused expressions by default, but this behavior can be changed using the `ignoreDirectives` option.
 
 Sequence expressions (those using a comma, such as `a = 1, b = 2`) are always considered unused unless their return value is assigned or used in a condition evaluation, or a function call is made with the sequence expression value.
 
@@ -36,6 +36,7 @@ This rule, in its default state, does not require any arguments. If you would li
 * `allowTernary` set to `true` will enable you to use ternary operators in your expressions similarly to short circuit evaluations (Default: `false`).
 * `allowTaggedTemplates` set to `true` will enable you to use tagged template literals in your expressions (Default: `false`).
 * `enforceForJSX` set to `true` will flag unused JSX element expressions (Default: `false`).
+* `ignoreDirectives` set to `true` will prevent directives from being reported as unused expressions when linting with `ecmaVersion: 3` (Default: `false`).
 
 These options allow unused expressions *only if all* of the code paths either directly change the state (for example, assignment statement) or could have *side effects* (for example, function call).
 
@@ -277,6 +278,56 @@ const myFragment = <></>;
 
 :::
 
+### ignoreDirectives
+
+When set to `false` (default), this rule reports directives (like `"use strict"`) as unused expressions when linting with `ecmaVersion: 3`. This default behavior exists because ES3 environments do not formally support directives, meaning such strings are effectively unused expressions in that specific context.
+
+Set this option to `true` to prevent directives from being reported as unused, even when `ecmaVersion: 3` is specified. This option is primarily useful for projects that need to maintain a single codebase containing directives while supporting both older ES3 environments and modern (ES5+) environments.
+
+**Note:** In ES5+ environments, directives are always ignored regardless of this setting.
+
+Examples of **incorrect** code for the `{ "ignoreDirectives": false }` option and `ecmaVersion: 3`:
+
+::: incorrect { "ecmaVersion": 3, "sourceType": "script" }
+
+```js
+/*eslint no-unused-expressions: ["error", { "ignoreDirectives": false }]*/
+
+"use strict";
+"use asm"
+"use stricter";
+"use babel"
+"any other strings like this in the directive prologue";
+"this is still the directive prologue";
+
+function foo() {
+    "bar";
+}
+```
+
+:::
+
+Examples of **correct** code for the `{ "ignoreDirectives": true }` option and `ecmaVersion: 3`:
+
+::: correct { "ecmaVersion": 3, "sourceType": "script" }
+
+```js
+/*eslint no-unused-expressions: ["error", { "ignoreDirectives": true }]*/
+
+"use strict";
+"use asm"
+"use stricter";
+"use babel"
+"any other strings like this in the directive prologue";
+"this is still the directive prologue";
+
+function foo() {
+    "bar";
+}
+```
+
+:::
+
 ### TypeScript Support
 
 This rule supports TypeScript-specific expressions and follows these guidelines:
diff --git a/lib/rules/no-unused-expressions.js b/lib/rules/no-unused-expressions.js
@@ -55,6 +55,9 @@ module.exports = {
 					enforceForJSX: {
 						type: "boolean",
 					},
+					ignoreDirectives: {
+						type: "boolean",
+					},
 				},
 				additionalProperties: false,
 			},
@@ -66,6 +69,7 @@ module.exports = {
 				allowTernary: false,
 				allowTaggedTemplates: false,
 				enforceForJSX: false,
+				ignoreDirectives: false,
 			},
 		],
 
@@ -82,6 +86,7 @@ module.exports = {
 				allowTernary,
 				allowTaggedTemplates,
 				enforceForJSX,
+				ignoreDirectives,
 			},
 		] = context.options;
 
@@ -211,7 +216,8 @@ module.exports = {
 			ExpressionStatement(node) {
 				if (
 					Checker.isDisallowed(node.expression) &&
-					!isDirective(node)
+					!astUtils.isDirective(node) &&
+					!(ignoreDirectives && isDirective(node))
 				) {
 					context.report({ node, messageId: "unusedExpression" });
 				}
diff --git a/lib/types/rules.d.ts b/lib/types/rules.d.ts
@@ -3935,6 +3935,10 @@ export interface ESLintRules extends Linter.RulesRecord {
 				 * @default false
 				 */
 				enforceForJSX: boolean;
+				/**
+				 * @default false
+				 */
+				ignoreDirectives: boolean;
 			}>,
 		]
 	>;
diff --git a/tests/lib/rules/no-unused-expressions.js b/tests/lib/rules/no-unused-expressions.js
@@ -37,10 +37,6 @@ ruleTester.run("no-unused-expressions", rule, {
 		"delete foo.bar",
 		"void new C",
 		'"use strict";',
-		{
-			code: '"use strict";',
-			languageOptions: { ecmaVersion: 3, sourceType: "script" },
-		},
 		'"directive one"; "directive two"; f();',
 		'function foo() {"use strict"; return true; }',
 		{
@@ -117,6 +113,42 @@ ruleTester.run("no-unused-expressions", rule, {
 			options: [{ enforceForJSX: true }],
 			languageOptions: { parserOptions: { ecmaFeatures: { jsx: true } } },
 		},
+		{
+			code: '"use strict";',
+			options: [{ ignoreDirectives: true }],
+			languageOptions: { ecmaVersion: 3, sourceType: "script" },
+		},
+		{
+			code: '"directive one"; "directive two"; f();',
+			options: [{ ignoreDirectives: true }],
+			languageOptions: { ecmaVersion: 3, sourceType: "script" },
+		},
+		{
+			code: 'function foo() {"use strict"; return true; }',
+			options: [{ ignoreDirectives: true }],
+			languageOptions: { ecmaVersion: 3, sourceType: "script" },
+		},
+		{
+			code: 'function foo() {"directive one"; "directive two"; f(); }',
+			options: [{ ignoreDirectives: true }],
+			languageOptions: { ecmaVersion: 3, sourceType: "script" },
+		},
+		{
+			code: '"use strict";',
+			options: [{ ignoreDirectives: true }],
+		},
+		{
+			code: '"directive one"; "directive two"; f();',
+			options: [{ ignoreDirectives: true }],
+		},
+		{
+			code: 'function foo() {"use strict"; return true; }',
+			options: [{ ignoreDirectives: true }],
+		},
+		{
+			code: 'function foo() {"directive one"; "directive two"; f(); }',
+			options: [{ ignoreDirectives: true }],
+		},
 	],
 	invalid: [
 		{
@@ -358,6 +390,43 @@ ruleTester.run("no-unused-expressions", rule, {
 				},
 			],
 		},
+		{
+			code: "foo;",
+			options: [{ ignoreDirectives: true }],
+			errors: [
+				{ messageId: "unusedExpression", type: "ExpressionStatement" },
+			],
+		},
+		{
+			code: '"use strict";',
+			languageOptions: { ecmaVersion: 3, sourceType: "script" },
+			errors: [
+				{ messageId: "unusedExpression", type: "ExpressionStatement" },
+			],
+		},
+		{
+			code: '"directive one"; "directive two"; f();',
+			languageOptions: { ecmaVersion: 3, sourceType: "script" },
+			errors: [
+				{ messageId: "unusedExpression", type: "ExpressionStatement" },
+				{ messageId: "unusedExpression", type: "ExpressionStatement" },
+			],
+		},
+		{
+			code: 'function foo() {"use strict"; return true; }',
+			languageOptions: { ecmaVersion: 3, sourceType: "script" },
+			errors: [
+				{ messageId: "unusedExpression", type: "ExpressionStatement" },
+			],
+		},
+		{
+			code: 'function foo() {"directive one"; "directive two"; f(); }',
+			languageOptions: { ecmaVersion: 3, sourceType: "script" },
+			errors: [
+				{ messageId: "unusedExpression", type: "ExpressionStatement" },
+				{ messageId: "unusedExpression", type: "ExpressionStatement" },
+			],
+		},
 	],
 });
 
