feat!: no-unused-vars default caughtErrors to 'all' (#18043)

JoshuaKGoldberg · mdjermanovic · amareshsm · web-flow · commit 1a945890105d · 2024-02-01T13:14:53.000+05:30
* feat!: `no-unused-vars` default caughtErrors to 'all'

* docs: update no-unused-vars.md

* docs: mention caughtErrors in migrate-to-9.0.0.md

* chore: typo fix in docs/src/use/migrate-to-9.0.0.md

Co-authored-by: Milos Djermanovic &lt;milos.djermanovic@gmail.com&gt;

* chore: fix formatting in no-unused-vars.md

* fix: 'are'/'were' in docs/src/use/migrate-to-9.0.0.md

Co-authored-by: Amaresh  S M  &lt;amareshsm13@gmail.com&gt;

---------

Co-authored-by: Milos Djermanovic &lt;milos.djermanovic@gmail.com&gt;
Co-authored-by: Amaresh  S M &lt;amareshsm13@gmail.com&gt;
diff --git a/docs/src/rules/no-unused-vars.md b/docs/src/rules/no-unused-vars.md
@@ -132,12 +132,12 @@ var global_var = 42;
 
 This rule takes one argument which can be a string or an object. The string settings are the same as those of the `vars` property (explained below).
 
-By default this rule is enabled with `all` option for variables and `after-used` for arguments.
+By default this rule is enabled with `all` option for caught errors and variables, and `after-used` for arguments.
 
 ```json
 {
     "rules": {
-        "no-unused-vars": ["error", { "vars": "all", "args": "after-used", "caughtErrors": "none", "ignoreRestSiblings": false }]
+        "no-unused-vars": ["error", { "vars": "all", "args": "after-used", "caughtErrors": "all", "ignoreRestSiblings": false }]
     }
 }
 ```
@@ -283,20 +283,22 @@ The `caughtErrors` option is used for `catch` block arguments validation.
 
 It has two settings:
 
-* `none` - do not check error objects. This is the default setting.
-* `all` - all named arguments must be used.
+* `all` - all named arguments must be used. This is the default setting.
+* `none` - do not check error objects.
 
-#### caughtErrors: none
+#### caughtErrors: all
 
-Not specifying this rule is equivalent of assigning it to `none`.
+Not specifying this option is equivalent of assigning it to `all`.
 
-Examples of **correct** code for the `{ "caughtErrors": "none" }` option:
+Examples of **incorrect** code for the `{ "caughtErrors": "all" }` option:
 
-::: correct
+::: incorrect
 
 ```js
-/*eslint no-unused-vars: ["error", { "caughtErrors": "none" }]*/
+/*eslint no-unused-vars: ["error", { "caughtErrors": "all" }]*/
 
+// 1 error
+// "err" is defined but never used
 try {
     //...
 } catch (err) {
@@ -306,17 +308,15 @@ try {
 
 :::
 
-#### caughtErrors: all
+#### caughtErrors: none
 
-Examples of **incorrect** code for the `{ "caughtErrors": "all" }` option:
+Examples of **correct** code for the `{ "caughtErrors": "none" }` option:
 
-::: incorrect
+::: correct
 
 ```js
-/*eslint no-unused-vars: ["error", { "caughtErrors": "all" }]*/
+/*eslint no-unused-vars: ["error", { "caughtErrors": "none" }]*/
 
-// 1 error
-// "err" is defined but never used
 try {
     //...
 } catch (err) {
diff --git a/docs/src/use/migrate-to-9.0.0.md b/docs/src/use/migrate-to-9.0.0.md
@@ -33,6 +33,7 @@ The lists below are ordered roughly by the number of users each change is expect
 * [`no-restricted-imports` now accepts multiple config entries with the same `name`](#no-restricted-imports)
 * [`"eslint:recommended"` and `"eslint:all"` strings no longer accepted in flat config](#string-config)
 * [`no-inner-declarations` has a new default behavior with a new option](#no-inner-declarations)
+* [`no-unused-vars` now defaults `caughtErrors` to `"all"`](#no-unused-vars)
 
 ### Breaking changes for plugin developers
 
@@ -362,6 +363,33 @@ if (test) {
 
 **Related issue(s):** [#15576](https://github.com/eslint/eslint/issues/15576)
 
+## <a name="no-unused-vars"></a> `no-unused-vars` now defaults `caughtErrors` to `"all"`
+
+ESLint v9.0.0 changes the default value for the `no-unused-vars` rule's `caughtErrors` option.
+Previously it defaulted to `"none"` to never check whether caught errors were used.
+It now defaults to `"all"` to check caught errors for being used.
+
+```js
+/*eslint no-unused-vars: "error"*/
+try {}
+catch (error) {
+    // 'error' is defined but never used
+}
+```
+
+**To address:** If you want to allow unused caught errors, such as when writing code that will be directly run in an environment that does not support ES2019 optional catch bindings, set the `caughtErrors` option to `"none"`.
+Otherwise, delete the unused caught errors.
+
+```js
+/*eslint no-unused-vars: "error"*/
+try {}
+catch {
+    // no error
+}
+```
+
+**Related issue(s):** [#17974](https://github.com/eslint/eslint/issues/17974)
+
 ## <a name="removed-context-methods"></a> Removed multiple `context` methods
 
 ESLint v9.0.0 removes multiple deprecated methods from the `context` object and moves them onto the `SourceCode` object:
diff --git a/lib/rules/no-unused-vars.js b/lib/rules/no-unused-vars.js
@@ -92,7 +92,7 @@ module.exports = {
             vars: "all",
             args: "after-used",
             ignoreRestSiblings: false,
-            caughtErrors: "none"
+            caughtErrors: "all"
         };
 
         const firstOption = context.options[0];
diff --git a/tests/lib/rules/no-unused-vars.js b/tests/lib/rules/no-unused-vars.js
@@ -113,7 +113,6 @@ ruleTester.run("no-unused-vars", rule, {
         "myFunc(function foo(){}.toString())",
         "function foo(first, second) {\ndoStuff(function() {\nconsole.log(second);});}; foo()",
         "(function() { var doSomething = function doSomething() {}; doSomething() }())",
-        "try {} catch(e) {}",
         "/*global a */ a;",
         { code: "var a=10; (function() { alert(a); })();", options: [{ vars: "all" }] },
         { code: "function g(bar, baz) { return baz; }; g();", options: [{ vars: "all" }] },
@@ -283,13 +282,17 @@ ruleTester.run("no-unused-vars", rule, {
         { code: "let x = 0; foo = (0, x = x + 1);", languageOptions: { ecmaVersion: 6 } },
 
         // caughtErrors
+        {
+            code: "try{}catch(err){}",
+            options: [{ caughtErrors: "none" }]
+        },
         {
             code: "try{}catch(err){console.error(err);}",
             options: [{ caughtErrors: "all" }]
         },
         {
-            code: "try{}catch(err){}",
-            options: [{ caughtErrors: "none" }]
+            code: "try{}catch(ignoreErr){}",
+            options: [{ caughtErrorsIgnorePattern: "^ignore" }]
         },
         {
             code: "try{}catch(ignoreErr){}",
@@ -299,7 +302,7 @@ ruleTester.run("no-unused-vars", rule, {
         // caughtErrors with other combinations
         {
             code: "try{}catch(err){}",
-            options: [{ vars: "all", args: "all" }]
+            options: [{ caughtErrors: "none", vars: "all", args: "all" }]
         },
 
         // Using object rest for variable omission
@@ -1122,6 +1125,10 @@ ruleTester.run("no-unused-vars", rule, {
         },
 
         // caughtErrors
+        {
+            code: "try{}catch(err){};",
+            errors: [definedError("err")]
+        },
         {
             code: "try{}catch(err){};",
             options: [{ caughtErrors: "all" }],
