eslint-plugin-fsd-imports-check 1.1.0

package/LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) 2026 ALTaww
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to persons to whom the
+Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO: THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTIONB OF ACTION, ACTION, WHETHER IN AN CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,466 @@
+# eslint-plugin-fsd-imports-check
+
+ESLint plugin for enforcing import rules in projects that use [Feature-Sliced Design (FSD)](https://feature-sliced.design/).
+
+GitLab: https://gitlab.com/ALTaww/eslint-plugin-fsd-imports-check
+
+## What does this plugin do?
+
+The plugin provides three rules for controlling imports between FSD modules:
+
+1. **`path-checker`** prevents absolute imports between files inside the same FSD slice. Such imports must use relative paths.
+
+2. **`layer-imports`** enforces the allowed dependency direction between FSD layers. For example, `features` can import from `entities` and `shared`, but cannot import from `widgets`, `pages`, or `app`.
+
+3. **`public-api-imports`** requires imports from another FSD module to use its public API instead of accessing internal files directly. The rule can optionally replace deep imports with public API imports.
+
+The rules work with both JavaScript and TypeScript source files.
+
+## Installation
+
+Install ESLint:
+
+```sh
+npm install eslint --save-dev
+```
+
+Then install the plugin:
+
+```sh
+npm install eslint-plugin-fsd-imports-check --save-dev
+```
+
+## Usage
+
+### ESLint 9 and 10
+
+For modern ESLint versions using flat config, import the plugin and register it under the `plugins` key.
+
+```js
+import { defineConfig } from "eslint/config";
+import fsdImportsCheck from "eslint-plugin-fsd-imports-check";
+
+export default defineConfig([
+  {
+    plugins: {
+      "fsd-imports-check": fsdImportsCheck,
+    },
+
+    rules: {
+      "fsd-imports-check/path-checker": "error",
+      "fsd-imports-check/layer-imports": "error",
+      "fsd-imports-check/public-api-imports": "error",
+    },
+  },
+]);
+```
+
+### ESLint 6–8
+
+For legacy ESLint configuration, add the plugin to the `plugins` array:
+
+```js
+module.exports = {
+  plugins: ["fsd-imports-check"],
+
+  rules: {
+    "fsd-imports-check/path-checker": "error",
+    "fsd-imports-check/layer-imports": "error",
+    "fsd-imports-check/public-api-imports": "error",
+  },
+};
+```
+
+The plugin is distributed as a CommonJS package, so the same package can be used with legacy and flat ESLint configurations.
+
+## Configuration example
+
+A typical FSD project can use the following configuration:
+
+```js
+import { defineConfig } from "eslint/config";
+import fsdImportsCheck from "eslint-plugin-fsd-imports-check";
+
+export default defineConfig([
+  {
+    files: ["**/*.{js,mjs,cjs,ts,tsx}"],
+
+    plugins: {
+      "fsd-imports-check": fsdImportsCheck,
+    },
+
+    rules: {
+      "fsd-imports-check/path-checker": [
+        "error",
+        {
+          alias: "@",
+        },
+      ],
+
+      "fsd-imports-check/layer-imports": [
+        "error",
+        {
+          alias: "@",
+          ignoreImports: ["**/testing"],
+        },
+      ],
+
+      "fsd-imports-check/public-api-imports": [
+        "error",
+        {
+          alias: "@",
+          autofix: true,
+          testFilesPatterns: ["**/*.test.ts", "**/*.stories.*"],
+        },
+      ],
+    },
+  },
+]);
+```
+
+## Rules
+
+<!-- begin auto-generated rules list -->
+
+🔧 Automatically fixable by the [`--fix` CLI option](https://eslint.org/docs/latest/use/command-line-interface#fixing-problems).
+
+| Name                                                   | Description                                                  | 🔧  |
+| :----------------------------------------------------- | :----------------------------------------------------------- | :-- |
+| [layer-imports](docs/rules/layer-imports.md)           | Checking right layer imports (shared, widgets, pages, etc.). |     |
+| [path-checker](docs/rules/path-checker.md)             | Feature sliced relative path checker.                        | 🔧  |
+| [public-api-imports](docs/rules/public-api-imports.md) | Enforces importing from public APIs of FSD modules.          | 🔧  |
+
+<!-- end auto-generated rules list -->
+
+## Rule Examples
+
+### `path-checker`
+
+Files belonging to the same slice should use relative imports.
+
+Invalid:
+
+```ts
+// src/entities/Article/ui/ArticleDetails.ts
+
+import { addCommentFormSlice } from "@/entities/Article/model/addCommentFormSlice";
+```
+
+Valid:
+
+```ts
+import { addCommentFormSlice } from "../../model/addCommentFormSlice";
+```
+
+The rule does not restrict imports between different slices:
+
+```ts
+// src/entities/Article/file.ts
+
+import { Profile } from "entities/Profile";
+```
+
+The rule can optionally fix invalid imports automatically.
+
+By default, `autofix` is disabled:
+
+```js
+{
+  alias: "@",
+  autofix: false,
+}
+```
+
+To enable automatic fixes:
+
+```js
+{
+  alias: "@",
+  autofix: true,
+}
+```
+
+### `layer-imports`
+
+The rule enforces the following dependency direction:
+
+```text
+app
+├── pages
+├── widgets
+├── features
+├── shared
+└── entities
+
+pages
+├── widgets
+├── features
+├── shared
+└── entities
+
+widgets
+├── features
+├── shared
+└── entities
+
+features
+├── shared
+└── entities
+
+entities
+└── shared
+
+shared
+└── shared
+```
+
+Invalid:
+
+```ts
+// src/features/Auth/ui/LoginForm.ts
+
+import { Header } from "@/widgets/Header";
+```
+
+Valid:
+
+```ts
+import { User } from "@/entities/User";
+import { Button } from "@/shared/Button";
+```
+
+Relative imports are also checked:
+
+```ts
+// src/shared/index.ts
+
+import { App } from "../app/App";
+```
+
+The import above is invalid because `shared` must not depend on `app`.
+
+Imports from external packages are ignored:
+
+```ts
+import React from "react";
+import { useLocation } from "react-router-dom";
+```
+
+Specific source files and imports can also be excluded with `ignoreFiles` and `ignoreImports`.
+
+### `public-api-imports`
+
+Other FSD modules should normally be imported through their public API.
+
+Invalid:
+
+```ts
+import { ArticleDetails } from "@/entities/Article/ui/ArticleDetails/ArticleDetails";
+```
+
+Valid:
+
+```ts
+import { ArticleDetails } from "@/entities/Article";
+```
+
+By default, `autofix` is disabled. When enabled, ESLint can automatically replace deep imports with public API imports:
+
+```sh
+npx eslint src --fix
+```
+
+The rule also supports a testing public API:
+
+```ts
+import { testHelper } from "@/entities/Article/testing";
+```
+
+This import is allowed only in files matching `testFilesPatterns`.
+
+For example:
+
+```js
+{
+  alias: "@",
+  testFilesPatterns: [
+    "**/*.test.ts",
+    "**/*.stories.*",
+  ],
+}
+```
+
+A custom testing Public API name can be configured with `testingFilename`:
+
+```js
+{
+  alias: "@",
+  testingFilename: "test-utils",
+}
+```
+
+Then the testing Public API becomes:
+
+```ts
+import { testHelper } from "@/entities/Article/test-utils";
+```
+
+## Options
+
+### `alias`
+
+Specifies the alias used for absolute imports.
+
+```js
+{
+  alias: "@",
+}
+```
+
+For example:
+
+```ts
+import { Article } from "@/entities/Article";
+```
+
+Without an alias, imports such as this are also supported:
+
+```ts
+import { Article } from "entities/Article";
+```
+
+### `ignoreFiles`
+
+Used by all three rules to exclude source files from validation.
+
+```js
+{
+  ignoreFiles: [
+    "**/*.test.ts",
+    "**/*.stories.*",
+  ],
+}
+```
+
+A matching source file is completely ignored by the rule.
+
+### `ignoreImports`
+
+Used by `path-checker`, `layer-imports`, and `public-api-imports` to exclude specific import paths from validation.
+
+```js
+{
+  alias: "@",
+  ignoreImports: [
+    "@/entities/Legacy/**",
+    "**/testing",
+  ],
+}
+```
+
+Matching imports are ignored.
+
+### `autofix`
+
+Used by `path-checker` and `public-api-imports` to enable automatic source code fixes.
+
+The default value is `false`.
+
+For example:
+
+```js
+{
+  alias: "@",
+  autofix: true,
+}
+```
+
+For `path-checker`, absolute imports inside the same slice are replaced with relative imports.
+
+For `public-api-imports`, deep imports are replaced with imports from the slice public API.
+
+### `testFilesPatterns`
+
+Used by `public-api-imports` to define files that are allowed to import a testing public API.
+
+```js
+{
+  alias: "@",
+  testFilesPatterns: [
+    "**/*.test.ts",
+    "**/*.stories.*",
+  ],
+}
+```
+
+Only matching files can import:
+
+```ts
+import { testHelper } from "@/entities/Article/testing";
+```
+
+### `testingFilename`
+
+Used by `public-api-imports` to change the name of the testing Public API path segment.
+
+The default value is `testing`.
+
+For example:
+
+```js
+{
+  alias: "@",
+  testingFilename: "test-utils",
+}
+```
+
+allows:
+
+```ts
+import { testHelper } from "@/entities/Article/test-utils";
+```
+
+## Auto-fix
+
+The following rules provide automatic fixes when `autofix: true` is configured:
+
+- `path-checker`
+- `public-api-imports`
+
+Run ESLint with:
+
+```sh
+npx eslint . --fix
+```
+
+`layer-imports` only reports architecture violations and does not modify source code.
+
+## Requirements
+
+The plugin declares ESLint as a peer dependency and can be used with supported ESLint versions that satisfy the package configuration.
+
+Modern ESLint versions use flat configuration:
+
+```text
+eslint.config.js
+eslint.config.mjs
+eslint.config.cjs
+```
+
+Older ESLint versions can use:
+
+```text
+.eslintrc.js
+.eslintrc.json
+```
+
+The plugin itself is implemented in TypeScript and distributed as compiled JavaScript.
+
+## Documentation
+
+Detailed documentation for each rule:
+
+- [layer-imports](docs/rules/layer-imports.md)
+- [path-checker](docs/rules/path-checker.md)
+- [public-api-imports](docs/rules/public-api-imports.md)
+

package/docs/rules/layer-imports.md

@@ -0,0 +1,188 @@
+# fsd-imports-check/layer-imports
+
+📝 Checking right layer imports (shared, widgets, pages, etc.).
+
+<!-- end auto-generated rule header -->
+
+The rule enforces the dependency direction between layers in a Feature-Sliced Design (FSD) project.
+
+A layer can import only from the layers located below it in the project architecture. Imports that violate this dependency direction are reported as errors.
+
+The rule supports both absolute imports, such as `@/shared/Button`, and relative imports, such as `../../shared/Button`. Relative imports are resolved against the current file before the target layer is determined.
+
+Imports from external packages such as `react` or `react-router-dom` are ignored because they do not belong to the FSD layer structure.
+
+## Rule Details
+
+The following layer dependencies are allowed:
+
+| Current layer | Allowed imports                                      |
+| :------------ | :--------------------------------------------------- |
+| `app`         | `pages`, `widgets`, `features`, `shared`, `entities` |
+| `pages`       | `widgets`, `features`, `shared`, `entities`          |
+| `widgets`     | `features`, `shared`, `entities`                     |
+| `features`    | `shared`, `entities`                                 |
+| `entities`    | `shared`, `entities`                                 |
+| `shared`      | `shared`                                             |
+
+For example, `features` can import from `entities` and `shared`, but cannot import from `widgets`, `pages`, or `app`.
+
+Examples of **incorrect** code for this rule:
+
+```ts
+// src/features/Auth/ui/LoginForm.ts
+
+import { Header } from "@/widgets/Header";
+```
+
+```ts
+// src/shared/index.ts
+
+import { App } from "../app/App";
+```
+
+```ts
+// src/entities/Article/ui/ArticleDetails.ts
+
+import { Auth } from "@/features/Auth";
+```
+
+In these examples, the current layer imports from a layer that is not allowed by the FSD dependency direction.
+
+Examples of **correct** code for this rule:
+
+```ts
+// src/features/Auth/ui/LoginForm.ts
+
+import { User } from "@/entities/User";
+```
+
+```ts
+// src/features/Auth/ui/LoginForm.ts
+
+import { Button } from "@/shared/Button";
+```
+
+```ts
+// src/entities/Article/ui/ArticleDetails.ts
+
+import { Button } from "../../shared/Button";
+```
+
+Relative imports are also checked when they point to another FSD layer:
+
+```ts
+// src/entities/Article/file.ts
+
+import { Button } from "../../shared/Button";
+```
+
+Here the relative path resolves to the `shared` layer, which is allowed for `entities`.
+
+External dependencies are ignored:
+
+```ts
+import React from "react";
+import { useLocation } from "react-router-dom";
+```
+
+### Options
+
+<!-- begin auto-generated rule options list -->
+
+| Name            | Description                                            | Type     | Default |
+| :-------------- | :----------------------------------------------------- | :------- | :------ |
+| `alias`         | Alias used for absolute imports, for example '@'.      | String   | ``      |
+| `ignoreFiles`   | Glob patterns for source files that should be ignored. | String[] | `[]`    |
+| `ignoreImports` | Glob patterns for imports that should be ignored.      | String[] | `[]`    |
+
+<!-- end auto-generated rule options list -->
+
+### `alias`
+
+The `alias` option specifies the alias used for absolute project imports.
+
+For example:
+
+```js
+{
+  alias: "@";
+}
+```
+
+the following import is treated as an import from the `shared` layer:
+
+```ts
+import { Button } from "@/shared/Button";
+```
+
+Without an alias, imports such as the following are also supported:
+
+```ts
+import { Button } from "shared/Button";
+```
+
+### `ignoreFiles`
+
+The `ignoreFiles` option allows entire source files to be excluded from layer checking.
+
+Patterns use glob syntax.
+
+For example:
+
+```js
+{
+  alias: "@",
+  ignoreFiles: [
+    "**/*.stories.tsx",
+    "**/*.test.ts"
+  ]
+}
+```
+
+With this configuration, imports inside matching files are not checked by `layer-imports`.
+
+This can be useful for Storybook files, tests, generated files, or other parts of the project that intentionally do not follow the regular layer dependency rules.
+
+### `ignoreImports`
+
+The `ignoreImports` option allows individual imports to be excluded from layer checking.
+
+Patterns use glob syntax.
+
+For example:
+
+```js
+{
+  alias: "@",
+  ignoreImports: [
+    "**/testing",
+    "**/testing/**",
+    "**/*.module.scss"
+  ]
+}
+```
+
+The following imports will then be ignored by the rule:
+
+```ts
+import { testHelper } from "@/features/Auth/testing";
+```
+
+```ts
+import styles from "@/features/Auth/ui/LoginForm.module.scss";
+```
+
+Unlike `ignoreFiles`, this option does not disable checking for the entire file. Other imports in the same file are still checked.
+
+## When Not To Use It
+
+Do not use this rule if the project does not follow Feature-Sliced Design or intentionally allows dependencies between layers that violate the standard FSD dependency direction.
+
+It may also be inappropriate for projects with a different architectural model or for parts of the codebase where layer boundaries are intentionally relaxed.
+
+## Further Reading
+
+- [Feature-Sliced Design](https://feature-sliced.design/)
+- [Feature-Sliced Design: Layers](https://feature-sliced.design/docs/reference/layers)
+