docs: Add troubleshooting info for plugin compatibility (#18451)

* docs: Add troubleshooting info for plugin compatibility

* Update docs/src/use/configure/plugins.md

Co-authored-by: Milos Djermanovic <milos.djermanovic@gmail.com>

* Update docs/src/use/configure/plugins.md

Co-authored-by: Milos Djermanovic <milos.djermanovic@gmail.com>

---------

Co-authored-by: Milos Djermanovic <milos.djermanovic@gmail.com>

docs/src/use/configure/migration-guide.md

@@ -78,6 +78,10 @@ export default [
 ];
 ```
 
+::: tip
+If you import a plugin and get an error such as "TypeError: context.getScope is not a function", then that means the plugin has not yet been updated to the ESLint v9.x rule API. While you should file an issue with the particular plugin, you can manually patch the plugin to work in ESLint v9.x using the [compatibility utilities](https://eslint.org/blog/2024/05/eslint-compatibility-utilities/).
+:::
+
 ### Custom Parsers
 
 In eslintrc files, importing a custom parser is similar to importing a plugin: you use a string to specify the name of the parser.

docs/src/use/configure/plugins.md

@@ -214,3 +214,8 @@ export default [
 ```
 
 ESLint only lints named code blocks when they are JavaScript files or if they match a `files` entry in a config object. Be sure to add a config object with a matching `files` entry if you want to lint non-JavaScript named code blocks.
+
+## Common Problems
+
+* [Plugin rules using the ESLint < v9.0.0 API](../troubleshooting/v9-rule-api-changes)
+* [Plugin configurations have not been upgraded to flat config](migration-guide#using-eslintrc-configs-in-flat-config)

docs/src/use/troubleshooting/index.md

@@ -9,6 +9,12 @@ eleventyNavigation:
 
 This page serves as a reference for common issues working with ESLint.
 
+## Configuration
+
+* [`TypeError: context.getScope is not a function`](./v9-rule-api-changes)
+
+## Legacy (eslintrc) Configuration
+
 * [`ESLint couldn't determine the plugin … uniquely`](./couldnt-determine-the-plugin-uniquely)
 * [`ESLint couldn't find the config … to extend from`](./couldnt-find-the-config)
 * [`ESLint couldn't find the plugin …`](./couldnt-find-the-plugin)

docs/src/use/troubleshooting/v9-rule-api-changes.md

@@ -0,0 +1,40 @@
+---
+title: "TypeError: context.getScope is not a function"
+eleventyNavigation:
+    key: v9 rule api changes
+    parent: troubleshooting
+    title: "TypeError: context.getScope is not a function"
+---
+
+## Symptoms
+
+When using ESLint v9.0.0 or later with a plugin, you may see one of the following errors:
+
+```plaintext
+TypeError: context.getScope is not a function
+TypeError: context.getAncestors is not a function
+TypeError: context.markVariableAsUsed is not a function
+TypeError: context.getDeclaredVariables is not a function
+```
+
+## Cause
+
+ESLint v9.0.0 introduces [changes to the rules API](https://eslint.org/blog/2023/09/preparing-custom-rules-eslint-v9/) that plugin rules use, which included moving some methods from the `context` object to the `sourceCode` object. If you're seeing one of these errors, that means the plugin has not yet been updated to use the new rules API.
+
+## Resolution
+
+Common resolutions for this issue include:
+
+* Upgrade the plugin to the latest version
+* Use the [compatibility utilities](https://eslint.org/blog/2024/05/eslint-compatibility-utilities/) to patch the plugin in your config file
+
+::: important
+If you are already using the latest version of the plugin and you need to use the compatibility utilities to make the plugin work with ESLint v9.0.0 and later, make sure to open an issue on the plugin's repository to ask the maintainer to make the necessary API changes.
+:::
+
+## Resources
+
+For more information, see:
+
+* [Configure Plugins](../configure/plugins) for documentation on how to configure plugins
+* [Create Plugins](../../extend/plugins#configs-in-plugins) for documentation on how to define plugins