fix(eslint-plugin): [return-await] clean up in-try-catch detection and make autofixes safe

[kirkwaiblinger]

PR Checklist

• Addresses an existing open issue:
  1. fixes Bug: [return-await] unsafe autofixes in error handling code #8661
  2. fixes Bug: [return-await] awaited promise allowed in terminal catch block #8663
  3. fixes Bug: [return-await] should handle nested try-catch-finally blocks with "in-try-catch" option #8907
• That issue was marked as accepting prs
• Steps in Contributing were taken

Overview

These 3 bugs are closely related, and the code is largely interdependent, so I figured it would be easiest to group into 1 PR. We can do sequential PRs instead if need be.

The diff looks like there's a lot going on, but I think it's actually not so bad, if we go step-by-step. (Then again, this is all swimming around in my head so it probably makes more sense to me than to a reader):

1. docs changes. Not tied to any specific code change, just tried to improve them somewhat.
2. Refactoring/Logic simplification - when determining whether a node is inside of a try, catch, or finally, we now just find the nearest try-catch-finally statement and work from there, rather than checking each ancestor separately. (bye-bye inTry, inCatch, hasFinallyBlock, isReturnPromiseInFinally, all replaced by findEnclosingTryStatement)
3. Logic change - extract error-handling logic from in-try-catch into a helper function that now also checks nested try-catch-finally statements, rather than just the closest one found (affectsExplicitErrorHandling), fixing Bug: [return-await] should handle nested try-catch-finally blocks with "in-try-catch" option #8907.
4. Trivially fix the control flow in the in-try-catch thanks to the above helper, fixing Bug: [return-await] awaited promise allowed in terminal catch block #8663.
5. Logic change - Use the above utilities outside of the in-try-catch option as well, as the condition for whether to autofix or suggest a fix, fixing Bug: [return-await] unsafe autofixes in error handling code #8661.
6. Lots of accompanying test changes. With the exception of one valid test change for Bug: [return-await] awaited promise allowed in terminal catch block #8663, all the test changes are just changing autofixes to suggestions (Bug: [return-await] unsafe autofixes in error handling code #8661). The test additions are to handle the nested try-catch-finallys (Bug: [return-await] should handle nested try-catch-finally blocks with "in-try-catch" option #8907)

[typescript-eslint]

Thanks for the PR, @kirkwaiblinger!

typescript-eslint is a 100% community driven project, and we are incredibly grateful that you are contributing to that community.

The core maintainers work on this in their personal time, so please understand that it may not be possible for them to review your work immediately.

Thanks again!

---

🙏 Please, if you or your company is finding typescript-eslint valuable, help us sustain the project by sponsoring it transparently on https://opencollective.com/typescript-eslint.

[netlify]

✅ Deploy Preview for typescript-eslint ready!

Name	Link
🔨 Latest commit	1777ac9
🔍 Latest deploy log	https://app.netlify.com/sites/typescript-eslint/deploys/66346aba53d22600088730ba
😎 Deploy Preview	https://deploy-preview-9031--typescript-eslint.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.
Lighthouse	1 paths audited Performance: 98 (🟢 up 1 from production) Accessibility: 100 (no change from production) Best Practices: 92 (no change from production) SEO: 98 (no change from production) PWA: 80 (no change from production) View the detailed breakdown and full score reports

---

To edit notification comments on pull requests, go to your Netlify site configuration.

[nx-cloud]

☁️ Nx Cloud Report

CI is running/has finished running commands for commit 1777ac9. As they complete they will appear below. Click to see the status, the terminal output, and the build insights.

📂 See all runs for this CI Pipeline Execution

---

✅ Successfully ran 31 targets

• nx test eslint-plugin --coverage=false
• nx test eslint-plugin
• nx test type-utils --coverage=false
• nx run types:build
• nx run repo-tools:postinstall-script
• nx test typescript-eslint --coverage=false
• nx test utils --coverage=false
• nx test typescript-estree --coverage=false
• nx test visitor-keys --coverage=false
• nx test scope-manager --coverage=false
• nx test repo-tools --coverage=false
• nx run-many --target=build --parallel --exclude=website --exclude=website-eslint
• nx test rule-schema-to-typescript-types --coverage=false
• nx test ast-spec --coverage=false
• nx test parser --coverage=false
• nx test eslint-plugin-internal --coverage=false
• nx run-many --target=lint --parallel --exclude eslint-plugin
• nx test typescript-eslint
• nx test utils
• nx test visitor-keys
• nx test typescript-estree
• nx test type-utils
• nx test scope-manager
• nx test rule-schema-to-typescript-types
• nx test parser
• nx test repo-tools
• nx test eslint-plugin-internal
• nx run-many --target=typecheck --parallel
• nx run repo-tools:generate-configs
• nx test ast-spec
• nx run integration-tests:test

---

Sent with 💌 from NxCloud.

[kirkwaiblinger]

This just tests 3 totally separable errors, so I broke it up into 3 separate tests.

[kirkwaiblinger]

The return statements were just wrong. Directly caused #8663 and played into #8907 as well.

With the inCatch/hasFinallyBlock etc logic extracted to the affectsErrorHandling variable, they now correctly are included in the preceeding branch (enforcing removing the await).

[kirkwaiblinger]

The thought is that one day (soon) there will be a || affectsExplicitResourceManagement(expression) 🙏 #7889/#9044