feat: Add --pass-on-unpruned-suppressions CLI option (#19773)

mdjermanovic · nzakas · web-flow · commit a95721f1064f · 2025-05-29T11:36:14.000-04:00
* feat: Add `--pass-on-unpruned-suppressions` CLI option Fixes #19723 * Update docs/src/use/command-line-interface.md Co-authored-by: Nicholas C. Zakas <nicholas@humanwhocodes.com> * Update tests/bin/eslint.js Co-authored-by: Nicholas C. Zakas <nicholas@humanwhocodes.com> * assert error message * fix typo --------- Co-authored-by: Nicholas C. Zakas <nicholas@humanwhocodes.com>
diff --git a/docs/src/use/command-line-interface.md b/docs/src/use/command-line-interface.md
@@ -142,6 +142,7 @@ Suppressing Violations:
   --suppress-rule [String]        Suppress specific rules
   --suppressions-location path::String  Specify the location of the suppressions file
   --prune-suppressions            Prune unused suppressions - default: false
+  --pass-on-unpruned-suppressions Ignore unused suppressions - default: false
 
 Miscellaneous:
   --init                          Run config initialization wizard - default: false
@@ -904,6 +905,19 @@ Prune unused suppressions from the suppressions file. This option is useful when
     args: ["\"src/**/*.js\"", "--prune-suppressions"]
 }) }}
 
+#### `--pass-on-unpruned-suppressions`
+
+Ignore unused suppressions. By default, ESLint exits with exit code `2` and displays an error message if there are unused suppressions in the suppressions file. When you use this flag, unused suppressions do not affect the exit code and ESLint doesn't output an error about unused suppressions.
+
+- **Argument Type**: No argument.
+
+##### `--pass-on-unpruned-suppressions` example
+
+{{ npx_tabs ({
+    package: "eslint",
+    args: ["\"src/**/*.js\"", "--pass-on-unpruned-suppressions"]
+}) }}
+
 ### Miscellaneous
 
 #### `--init`
diff --git a/docs/src/use/suppressions.md b/docs/src/use/suppressions.md
@@ -60,4 +60,10 @@ To remove the suppressions that are no longer needed, you can use the `--prune-s
 eslint --prune-suppressions
 ```
 
+To ignore unused suppressions when calculating the exit code and not report an error about unused suppressions, you can use the `--pass-on-unpruned-suppressions` flag.
+
+```bash
+eslint --pass-on-unpruned-suppressions
+```
+
 For more information on the available CLI options, refer to [Command Line Interface](./command-line-interface).
diff --git a/lib/cli.js b/lib/cli.js
@@ -734,17 +734,21 @@ const cli = {
 				);
 			}
 
-			const unusedSuppressionsCount =
-				Object.keys(unusedSuppressions).length;
+			if (!options.passOnUnprunedSuppressions) {
+				const unusedSuppressionsCount =
+					Object.keys(unusedSuppressions).length;
 
-			if (unusedSuppressionsCount > 0) {
-				log.error(
-					"There are suppressions left that do not occur anymore. Consider re-running the command with `--prune-suppressions`.",
-				);
-				debug(JSON.stringify(unusedSuppressions, null, 2));
+				if (unusedSuppressionsCount > 0) {
+					log.error(
+						"There are suppressions left that do not occur anymore. Consider re-running the command with `--prune-suppressions`.",
+					);
+					debug(JSON.stringify(unusedSuppressions, null, 2));
+
+					return 2;
+				}
 			}
 
-			if (shouldExitForFatalErrors || unusedSuppressionsCount > 0) {
+			if (shouldExitForFatalErrors) {
 				return 2;
 			}
 
diff --git a/lib/options.js b/lib/options.js
@@ -66,6 +66,7 @@ const optionator = require("optionator");
  * @property {string[]} [suppressRule] Suppress specific rules
  * @property {string} [suppressionsLocation] Path to the suppressions file or directory
  * @property {boolean} [pruneSuppressions] Prune unused suppressions
+ * @property {boolean} [passOnUnprunedSuppressions] Ignore unused suppressions
  */
 
 //------------------------------------------------------------------------------
@@ -449,6 +450,12 @@ module.exports = function (usingFlatConfig) {
 				default: "false",
 				description: "Prune unused suppressions",
 			},
+			{
+				option: "pass-on-unpruned-suppressions",
+				type: "Boolean",
+				default: "false",
+				description: "Ignore unused suppressions",
+			},
 			{
 				heading: "Miscellaneous",
 			},
diff --git a/tests/bin/eslint.js b/tests/bin/eslint.js
@@ -528,6 +528,8 @@ describe("bin/eslint.js", () => {
 		const ARGS_WITH_PRUNE_SUPPRESSIONS = ARGS_WITHOUT_SUPPRESSIONS.concat(
 			"--prune-suppressions",
 		);
+		const ARGS_WITH_PASS_ON_UNPRUNED_SUPPRESSIONS =
+			ARGS_WITHOUT_SUPPRESSIONS.concat("--pass-on-unpruned-suppressions");
 
 		const SUPPRESSIONS_FILE_WITH_INDENT = {
 			[SOURCE_PATH]: {
@@ -1058,7 +1060,7 @@ describe("bin/eslint.js", () => {
 				return Promise.all([exitCodeAssertion, outputAssertion]);
 			});
 
-			it("exits with code 2, when there are unused violations", () => {
+			it("exits with code 2, when there are unused suppressions", () => {
 				const suppressions = structuredClone(
 					SUPPRESSIONS_FILE_ALL_ERRORS,
 				);
@@ -1071,7 +1073,87 @@ describe("bin/eslint.js", () => {
 
 				const child = runESLint(ARGS_WITHOUT_SUPPRESSIONS);
 
-				return assertExitCode(child, 2);
+				const exitCodeAssertion = assertExitCode(child, 2);
+				const outputAssertion = getOutput(child).then(output => {
+					assert.include(
+						output.stderr,
+						"There are suppressions left that do not occur anymore. Consider re-running the command with `--prune-suppressions`.",
+					);
+				});
+
+				return Promise.all([exitCodeAssertion, outputAssertion]);
+			});
+
+			it("exits with code 0, when there are unused suppressions and the --pass-on-unpruned-suppressions flag is used", () => {
+				const suppressions = structuredClone(
+					SUPPRESSIONS_FILE_ALL_ERRORS,
+				);
+
+				suppressions[SOURCE_PATH].indent.count = 10;
+				fs.writeFileSync(
+					SUPPRESSIONS_PATH,
+					JSON.stringify(suppressions, null, 2),
+				);
+
+				const child = runESLint(
+					ARGS_WITH_PASS_ON_UNPRUNED_SUPPRESSIONS,
+				);
+
+				const exitCodeAssertion = assertExitCode(child, 0);
+				const outputAssertion = getOutput(child).then(output => {
+					assert.notInclude(output.stderr, "suppressions left");
+				});
+
+				return Promise.all([exitCodeAssertion, outputAssertion]);
+			});
+
+			it("exits with code 1 if there are unsuppressed lint errors, when there are unused suppressions and the --pass-on-unpruned-suppressions flag is used (1)", () => {
+				const suppressions = structuredClone(
+					SUPPRESSIONS_FILE_ALL_ERRORS,
+				);
+
+				suppressions[SOURCE_PATH].indent.count = 10;
+				suppressions[SOURCE_PATH]["no-sparse-arrays"].count--;
+				fs.writeFileSync(
+					SUPPRESSIONS_PATH,
+					JSON.stringify(suppressions, null, 2),
+				);
+
+				const child = runESLint(
+					ARGS_WITH_PASS_ON_UNPRUNED_SUPPRESSIONS,
+				);
+
+				const exitCodeAssertion = assertExitCode(child, 1);
+				const outputAssertion = getOutput(child).then(output => {
+					assert.notInclude(output.stderr, "suppressions left");
+				});
+
+				return Promise.all([exitCodeAssertion, outputAssertion]);
+			});
+
+			it("exits with code 1 if there are unsuppressed lint errors, when there are unused suppressions and the --pass-on-unpruned-suppressions flag is used (2)", () => {
+				const suppressions = structuredClone(
+					SUPPRESSIONS_FILE_ALL_ERRORS,
+				);
+
+				suppressions[SOURCE_PATH].indent.count = 10;
+				fs.writeFileSync(
+					SUPPRESSIONS_PATH,
+					JSON.stringify(suppressions, null, 2),
+				);
+
+				const child = runESLint(
+					ARGS_WITH_PASS_ON_UNPRUNED_SUPPRESSIONS.concat(
+						"--rule=no-restricted-syntax:[error, 'IfStatement']",
+					),
+				);
+
+				const exitCodeAssertion = assertExitCode(child, 1);
+				const outputAssertion = getOutput(child).then(output => {
+					assert.notInclude(output.stderr, "suppressions left");
+				});
+
+				return Promise.all([exitCodeAssertion, outputAssertion]);
 			});
 
 			it("prunes the suppressions file, when the --prune-suppressions flag is used", () => {
