Fix mistakes and clarify docs for no-restricted-paths

docs/rules/no-restricted-paths.md

@@ -9,190 +9,212 @@ In order to prevent such scenarios this rule allows you to define restricted zon
 
 ## Rule Details
 
-This rule has one option. The option is an object containing the definition of all restricted `zones` and the optional `basePath` which is used to resolve relative paths within.
-The default value for `basePath` is the current working directory.
-
-Each zone consists of the `target` paths, a `from` paths, and an optional `except` and `message` attribute.
-
- - `target` contains the paths where the restricted imports should be applied. It can be expressed by
-   - directory string path that matches all its containing files
-   - glob pattern matching all the targeted files
-   - an array of multiple of the two types above
- - `from` paths define the folders that are not allowed to be used in an import. It can be expressed by
-   - directory string path that matches all its containing files
-   - glob pattern matching all the files restricted to be imported
-   - an array of multiple directory string path
-   - an array of multiple glob patterns
- - `except` may be defined for a zone, allowing exception paths that would otherwise violate the related `from`. Note that it does not alter the behaviour of `target` in any way.
-   - in case `from` contains only glob patterns, `except` must be an array of glob patterns as well
-   - in case `from` contains only directory path, `except` is relative to `from` and cannot backtrack to a parent directory
- - `message` - will be displayed in case of the rule violation.
+This rule has one option, which is an object containing all `zones` where restrictions will be applied, plus an optional `basePath` used to resolve relative paths within each zone.
+The default for `basePath` is the current working directory.
+
+Each zone consists of a `target`, a `from`, and optional `except` and `message` attributes.
+
+ - `target` - Identifies which files are part of the zone. It can be expressed as:
+   - A simple directory path, matching all files contained recursively within it
+   - A glob pattern
+   - An array of any of the two types above
+   - *Example: `target: './client'` - this zone consists of all files under the 'client' dir*
+ - `from` - Identifies folders from which the zone is not allowed to import. It can be expressed as:
+   - A simple directory path, matching all files contained recursively within it
+   - A glob pattern
+   - An array of only simple directories, or of only glob patterns (mixing both types within the array is not allowed)
+   - *Example: `from: './server'` - this zone is not allowed to import anything from the 'server' dir*
+ - `except` - Optional. Allows exceptions that would otherwise violate the related `from`. Note that it does not alter the behaviour of `target` in any way.
+   - If `from` is an array of glob patterns, `except` must be an array of glob patterns as well.
+   - If `from` is an array of simple directories, `except` is relative to `from` and cannot backtrack to a parent directory.
+   - *Example: `except: './server/config'` this zone is allowed to import server config, even if it can't import other server code*
+ - `message` - Optional. Displayed in case of rule violation.
+
+*Note: The `from` attribute is NOT matched literally against the import path string as it appears in the code. Instead, it's matched against the path to the imported file after it's been resolved against `basePath`.*
 
 ### Examples
 
-Given the following folder structure:
+Given this folder structure:
 
 ```pt
-my-project
+.
 ├── client
-│   └── foo.js
+│   ├── foo.js
 │   └── baz.js
 └── server
     └── bar.js
 ```
 
-and the current file being linted is `my-project/client/foo.js`.
+And this configuration:
 
-The following patterns are considered problems when configuration set to `{ "zones": [ { "target": "./client", "from": "./server" } ] }`:
+```json
+{
+  "zones": [
+    {
+      "target": "./client",
+      "from": "./server"
+    }
+  ]
+}
+```
+
+:x: The following is considered incorrect:
 
 ```js
+// client/foo.js
 import bar from '../server/bar';
 ```
 
-The following patterns are not considered problems when configuration set to `{ "zones": [ { "target": "./client", "from": "./server" } ] }`:
+:white_check_mark: The following is considered correct:
 
 ```js
+// server/bar.js
 import baz from '../client/baz';
 ```
 
 ---------------
 
-Given the following folder structure:
+Given this folder structure:
 
 ```pt
-my-project
+.
 ├── client
-│   └── foo.js
-│   └── baz.js
+│   └── ...
 └── server
     ├── one
-    │   └── a.js
+    │   ├── a.js
     │   └── b.js
     └── two
+        └── a.js
 ```
 
-and the current file being linted is `my-project/server/one/a.js`.
-
-and the current configuration is set to:
+And this configuration:
 
 ```json
-{ "zones": [ {
-    "target": "./tests/files/restricted-paths/server/one",
-    "from": "./tests/files/restricted-paths/server",
-    "except": ["./one"]
-} ] }
+{
+  "zones": [
+    {
+      "target": "./server/one",
+      "from": "./server",
+      "except": ["./one"]
+    }
+  ]
+}
 ```
 
-The following pattern is considered a problem:
+:x: The following is considered incorrect:
 
 ```js
+// server/one/a.js
 import a from '../two/a'
 ```
 
-The following pattern is not considered a problem:
+:white_check_mark: The following is considered correct:
 
 ```js
+// server/one/a.js
 import b from './b'
-
 ```
 
 ---------------
 
-Given the following folder structure:
+Given this folder structure:
 
 ```pt
-my-project
-├── client
-    └── foo.js
+.
+└── client
+    ├── foo.js
     └── sub-module
-        └── bar.js
+        ├── bar.js
         └── baz.js
-
 ```
 
-and the current configuration is set to:
+And this configuration:
 
 ```json
-{ "zones": [ {
-    "target": "./tests/files/restricted-paths/client/!(sub-module)/**/*",
-    "from": "./tests/files/restricted-paths/client/sub-module/**/*",
-} ] }
+{
+  "zones": [
+    {
+      "target": "./client/!(sub-module)/**/*",
+      "from": "./client/sub-module/**/*",
+    }
+  ]
+}
 ```
 
-The following import is considered a problem in `my-project/client/foo.js`:
+:x: The following is considered incorrect:
 
 ```js
+// client/foo.js
 import a from './sub-module/baz'
 ```
 
-The following import is not considered a problem in `my-project/client/sub-module/bar.js`:
+:white_check_mark: The following is considered correct:
 
 ```js
+// client/sub-module/bar.js
 import b from './baz'
 ```
 
 ---------------
 
-Given the following folder structure:
+Given this folder structure:
 
 ```pt
-my-project
-└── one
-   └── a.js
-   └── b.js
-└── two
-   └── a.js
-   └── b.js
+.
+├── one
+│   ├── a.js
+│   └── b.js
+├── two
+│   ├── a.js
+│   └── b.js
 └── three
-   └── a.js
-   └── b.js
+    ├── a.js
+    └── b.js
 ```
 
-and the current configuration is set to:
+And this configuration:
 
 ```json
 {
   "zones": [
     {
-      "target": ["./tests/files/restricted-paths/two/*", "./tests/files/restricted-paths/three/*"],
-      "from": ["./tests/files/restricted-paths/one", "./tests/files/restricted-paths/three"],
+      "target": [
+        "./two/*",
+        "./three/*"
+      ],
+      "from": [
+        "./one",
+        "./three"
+      ]
     }
   ]
 }
 ```
 
-The following patterns are not considered a problem in `my-project/one/b.js`:
+:white_check_mark: The following is considered correct:
 
 ```js
+// one/b.js
 import a from '../three/a'
-```
-
-```js
 import a from './a'
 ```
 
-The following pattern is not considered a problem in `my-project/two/b.js`:
-
 ```js
+// two/b.js
 import a from './a'
 ```
 
-The following patterns are considered a problem in `my-project/two/a.js`:
+:x: The following is considered incorrect:
 
 ```js
+// two/a.js
 import a from '../one/a'
-```
-
-```js
 import a from '../three/a'
 ```
 
-The following patterns are considered a problem in `my-project/three/b.js`:
-
 ```js
+// three/b.js
 import a from '../one/a'
-```
-
-```js
 import a from './a'
 ```