From cee8482844f14e10f134c923e25ac86002d329d5 Mon Sep 17 00:00:00 2001 From: Greg Reimer Date: Thu, 27 Mar 2025 13:39:20 -0600 Subject: [PATCH 1/2] Update no-restricted-paths.md Clarifies the wording to minimize ambiguity, and also fixes some errors in the documentation. --- docs/rules/no-restricted-paths.md | 181 +++++++++++++++++------------- 1 file changed, 100 insertions(+), 81 deletions(-) diff --git a/docs/rules/no-restricted-paths.md b/docs/rules/no-restricted-paths.md index a905226c22..c9b105c445 100644 --- a/docs/rules/no-restricted-paths.md +++ b/docs/rules/no-restricted-paths.md @@ -9,190 +9,209 @@ 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 files where import restrictions will be applied. It can be expressed by: + - A simple directory path, matching all files contained recursively within it + - A glob pattern + - An array of any of the two types above + - `from` - Identifies the folders that targeted files are not allowed to import from. It can be expressed by: + - 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) + - `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. + - `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' ``` From f82095e272616ed190dc512ee2e8b2541535ce85 Mon Sep 17 00:00:00 2001 From: Greg Reimer Date: Thu, 27 Mar 2025 15:17:00 -0600 Subject: [PATCH 2/2] Update no-restricted-paths.md Add examples and clarify wording --- docs/rules/no-restricted-paths.md | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/docs/rules/no-restricted-paths.md b/docs/rules/no-restricted-paths.md index c9b105c445..5ba4b393e3 100644 --- a/docs/rules/no-restricted-paths.md +++ b/docs/rules/no-restricted-paths.md @@ -14,17 +14,20 @@ 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 files where import restrictions will be applied. It can be expressed by: + - `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 - - `from` - Identifies the folders that targeted files are not allowed to import from. It can be expressed by: + - *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`.*