Deprecate scopes

docs/deprecating-scopes.md

@@ -0,0 +1,76 @@
+# Deprecating scopes
+
+The [`scopes`](./rules/no-cross-imports.md#scopes-deprecated) option of the [`workspaces/no-cross-imports`](./rules/no-cross-imports.md) rule has been deprecated and will be removed in the next major version.
+
+Assuming the following project structure:
+
+```
+project
+└─── packages
+     └─── user-management/
+          └─── shared/
+               └─── package.json
+          └─── registration/
+               └─── package.json
+          └─── login/
+               └─── package.json
+```
+
+there are two ways to achieve the same result as the `scopes` option:
+
+### Using `overrides` (Recommended)
+
+The [`overrides`](https://eslint.org/docs/user-guide/configuring/configuration-files#how-do-overrides-work) key of the ESLint configuration allows you to apply rules differently to a specific set of files.
+
+```jsonc
+// inside "project/.eslintrc.json"
+{
+  // ...
+  "rules": {
+    // ...
+    "workspaces/no-cross-imports": "error"
+  },
+  "overrides": [
+    {
+      "files": ["packages/user-management/**/*"],
+      "rules": {
+        "workspaces/no-cross-imports": [
+          "error",
+          { "allow": ["@project/user-management-shared"] }
+        ]
+      }
+    }
+  ]
+}
+```
+
+### Using cascading configuration files
+
+The [cascading configuration files feature](https://eslint.org/docs/latest/use/configure/configuration-files#cascading-and-hierarchy) of ESLint allows you to create a configuration file in a subdirectory of your project.
+
+> [!WARNING]  
+> This feature will be deprecated in the next major version of ESLint, see [Flat config rollout plans](https://eslint.org/blog/2023/10/flat-config-rollout-plans).  
+> It is recommended to use [`overrides`](#using-overrides-recommended) instead.
+
+```jsonc
+// inside "project/.eslintrc.json"
+{
+  // ...
+  "rules": {
+    // ...
+    "workspaces/no-cross-imports": "error"
+  }
+}
+```
+
+```jsonc
+// inside "project/packages/user-management/.eslintrc.json"
+{
+  "rules": {
+    "workspaces/no-cross-imports": [
+      "error",
+      { "allow": ["@project/user-management-shared"] }
+    ]
+  }
+}
+```

docs/rules/no-cross-imports.md

@@ -47,7 +47,11 @@ import bar from "../B/bar";
 import foo from "./packages/B/foo";
 ```
 
-### scopes
+### scopes (**DEPRECATED**)
+
+> [!WARNING]  
+> This feature has been deprecated and will be removed in the next major version.  
+> For more information, see [Deprecating Scopes](../deprecating-scopes.md).
 
 Takes either a boolean or an options object. Defaults to `false`.
 

lib/rules/no-cross-imports.js

@@ -57,6 +57,8 @@ const filterSharedPackagesInCurrentScope =
     return locationArray[locationArray.length - 1] !== scopedSharingFolderName;
   };
 
+let scopesDeprecationShown = false;
+
 module.exports.create = (context) => {
   const {
     options: [{ allow = [], scopes = { enable: false } } = {}],
@@ -66,6 +68,14 @@ module.exports.create = (context) => {
   const scopedEnabled = scopes === true || !!scopes.enable;
   const scopedSharingFolderName = scopes.folderName || "shared";
 
+  if (scopedEnabled && !scopesDeprecationShown) {
+    scopesDeprecationShown = true;
+
+    console.warn(
+      "eslint-plugin-workspaces: workspaces/no-cross-imports 'scopes' option has been deprecated and will be removed in the next major version.\n\tFor more information, see https://github.com/joshuajaco/eslint-plugin-workspaces/blob/main/docs/deprecating-scopes.md",
+    );
+  }
+
   const workspaces = getWorkspaces(context);
 
   if (!workspaces) return {};