Deprecate scopes

Author: joshuajaco

docs/deprecating-scopes.md

@@ -0,0 +1,101 @@
+# 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.  
+It was made with a specific use case in mind, but it turned out to be too inflexible and confusing.  
+Since there are better ways to achieve the same result, the option will be removed.
+
+## Migration
+
+There are two ways to migrate from `scopes` using basic ESLint configuration:
+
+### 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.
+
+#### Example
+
+Assuming the following project structure:
+
+```
+project
+└─── packages
+     └─── user-management/
+          └─── shared/
+               └─── package.json
+          └─── registration/
+               └─── package.json
+          └─── login/
+               └─── package.json
+```
+
+Inside `project/.eslintrc.json`:
+
+```jsonc
+{
+  // ...
+  "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.
+
+#### Example
+
+Assuming the following project structure:
+
+```
+project
+└─── packages
+     └─── user-management/
+          └─── shared/
+               └─── package.json
+          └─── registration/
+               └─── package.json
+          └─── login/
+               └─── package.json
+```
+
+Inside `project/.eslintrc.json`:
+
+```jsonc
+{
+  // ...
+  "rules": {
+    // ...
+    "workspaces/no-cross-imports": "error"
+  }
+}
+```
+
+Inside `project/packages/user-management/.eslintrc.json`:
+
+```jsonc
+{
+  "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,24 @@ module.exports.create = (context) => {
   const scopedEnabled = scopes === true || !!scopes.enable;
   const scopedSharingFolderName = scopes.folderName || "shared";
 
+  /* istanbul ignore if */
+  if (
+    scopedEnabled &&
+    !scopesDeprecationShown &&
+    process.stdout &&
+    process.stdout.isTTY
+  ) {
+    scopesDeprecationShown = true;
+
+    console.warn(
+      "\x1b[1m", // bright
+      "\x1b[33m", // yellow text
+      "Warning:",
+      "\x1b[0m", // reset
+      "the 'scopes' option of the 'workspaces/no-cross-imports' rule has been deprecated and will be removed in the next major version. See https://github.com/joshuajaco/eslint-plugin-workspaces/blob/main/docs/deprecating-scopes.md for more information.",
+    );
+  }
+
   const workspaces = getWorkspaces(context);
 
   if (!workspaces) return {};