Add support for cross-imports with @x

packages/steiger-plugin-fsd/package.json

@@ -30,7 +30,7 @@
     }
   ],
   "dependencies": {
-    "@feature-sliced/filesystem": "^2.2.5",
+    "@feature-sliced/filesystem": "^2.4.0",
     "fastest-levenshtein": "^1.0.16",
     "lodash-es": "^4.17.21",
     "pluralize": "^8.0.0",

packages/steiger-plugin-fsd/src/forbidden-imports/README.md

@@ -36,6 +36,54 @@ flowchart BT
   pages/editor/ui/EditorPage.tsx --> pages/editor/ui/Editor.tsx
 ```
 
+```mermaid
+flowchart BT
+  subgraph shared
+    subgraph shared/ui[ui]
+      shared/ui/styles.ts[styles.ts]
+      shared/ui/Button.tsx[Button.tsx]
+      shared/ui/TextField.tsx[TextField.tsx]
+      shared/ui/index.ts[index.ts]
+    end
+  end
+
+  subgraph entities
+    subgraph entities/user[user]
+      subgraph entities/user/at-x[@x]
+        entities/user/at-x/product.ts[product.ts]
+      end
+      subgraph entities/user/ui[ui]
+        entities/user/ui/UserAvatar.tsx[UserAvatar.tsx]
+      end
+      entities/user/index.ts[index.ts]
+    end
+    subgraph entities/product[product]
+      subgraph entities/product/ui[ui]
+        entities/product/ui/ProductCard.tsx[ProductCard.tsx]
+      end
+      entities/product/index.ts[index.ts]
+    end
+  end
+
+  subgraph pages
+    subgraph pages/editor[editor]
+      subgraph pages/editor/ui[ui]
+        pages/editor/ui/EditorPage.tsx[EditorPage.tsx]
+        pages/editor/ui/Editor.tsx[Editor.tsx]
+      end
+      pages/editor/index.ts[index.ts]
+    end
+  end
+
+  shared/ui/Button.tsx --> shared/ui/styles.ts
+  shared/ui/TextField.tsx --> shared/ui/styles.ts
+  entities/user/ui/UserAvatar.tsx --> shared/ui/index.ts
+  entities/product/ui/ProductCard.tsx --> entities/user/at-x/product.ts
+  pages/editor/ui/Editor.tsx --> shared/ui/index.ts
+  pages/editor/ui/EditorPage.tsx --> shared/ui/index.ts
+  pages/editor/ui/EditorPage.tsx --> pages/editor/ui/Editor.tsx
+```
+
 Examples of project structures that fail this rule:
 
 ```mermaid

packages/steiger-plugin-fsd/src/forbidden-imports/index.spec.ts

@@ -33,9 +33,12 @@ vi.mock('node:fs', async (importOriginal) => {
       '/src/shared/ui/index.ts': '',
       '/src/entities/user/ui/UserAvatar.tsx': 'import { Button } from "@/shared/ui"',
       '/src/entities/user/index.ts': '',
+      '/src/entities/user/@x/product.ts': '',
       '/src/entities/product/ui/ProductCard.tsx': 'import { UserAvatar } from "@/entities/user"',
+      '/src/entities/product/ui/GoodProductCard.tsx': 'import { UserAvatar } from "@/entities/user/@x/product"',
       '/src/entities/product/index.ts': '',
       '/src/entities/cart/ui/SmallCart.tsx': 'import { App } from "@/app"',
+      '/src/entities/cart/ui/BadSmallCart.tsx': 'import { UserAvatar } from "@/entities/user/@x/product"',
       '/src/entities/cart/lib/count-cart-items.ts': 'import root from "@/app/root.ts"',
       '/src/entities/cart/lib/index.ts': '',
       '/src/entities/cart/index.ts': '',
@@ -145,7 +148,7 @@ it('reports errors on a project where a feature imports from a page', async () =
   ])
 })
 
-it('reports errors in a project where a lower level imports from files that are direct children of a higher level', async () => {
+it('reports errors on a project where a lower level imports from files that are direct children of a higher level', async () => {
   const root = parseIntoFsdRoot(
     `
       📂 shared
@@ -190,3 +193,78 @@ it('reports errors in a project where a lower level imports from files that are
     },
   ])
 })
+
+it('reports no errors on a project with cross-imports through @x', async () => {
+  const root = parseIntoFsdRoot(
+    `
+      📂 shared
+        📂 ui
+          📄 styles.ts
+          📄 Button.tsx
+          📄 TextField.tsx
+          📄 index.ts
+      📂 entities
+        📂 user
+          📂 @x
+            📄 product.ts
+          📂 ui
+            📄 UserAvatar.tsx
+          📄 index.ts
+        📂 product
+          📂 ui
+            📄 GoodProductCard.tsx
+          📄 index.ts
+      📂 pages
+        📂 editor
+          📂 ui
+            📄 EditorPage.tsx
+            📄 Editor.tsx
+          📄 index.ts
+    `,
+    joinFromRoot('src'),
+  )
+
+  expect((await forbiddenImports.check(root)).diagnostics).toEqual([])
+})
+
+it('reports errors on a project with incorrect cross-imports through @x', async () => {
+  const root = parseIntoFsdRoot(
+    `
+      📂 shared
+        📂 ui
+          📄 styles.ts
+          📄 Button.tsx
+          📄 TextField.tsx
+          📄 index.ts
+      📂 entities
+        📂 user
+          📂 @x
+            📄 product.ts
+          📂 ui
+            📄 UserAvatar.tsx
+          📄 index.ts
+        📂 product
+          📂 ui
+            📄 GoodProductCard.tsx
+          📄 index.ts
+        📂 cart
+          📂 ui
+            📄 BadSmallCart.tsx
+          📄 index.ts
+      📂 pages
+        📂 editor
+          📂 ui
+            📄 EditorPage.tsx
+            📄 Editor.tsx
+          📄 index.ts
+    `,
+    joinFromRoot('src'),
+  )
+
+  expect((await forbiddenImports.check(root)).diagnostics).toEqual([
+    {
+      message: `Forbidden cross-import from slice "user".`,
+      location: { path: joinFromRoot('src', 'entities', 'cart', 'ui', 'BadSmallCart.tsx') },
+    },
+  ])
+})

packages/steiger-plugin-fsd/src/forbidden-imports/index.ts

@@ -1,5 +1,6 @@
 import * as fs from 'node:fs'
-import { layerSequence, resolveImport } from '@feature-sliced/filesystem'
+import { join } from 'node:path'
+import { layerSequence, resolveImport, isCrossImportPublicApi } from '@feature-sliced/filesystem'
 import precinct from 'precinct'
 const { paperwork } = precinct
 import { parse as parseNearestTsConfig } from 'tsconfck'
@@ -38,12 +39,15 @@ const forbiddenImports = {
           sourceFile.layerName === dependencyLocation.layerName &&
           sourceFile.sliceName !== dependencyLocation.sliceName
         ) {
-          if (dependencyLocation.sliceName === null) {
-            diagnostics.push({
-              message: `Forbidden cross-import from segment "${dependencyLocation.segmentName}".`,
-              location: { path: sourceFile.file.path },
+          if (
+            dependencyLocation.sliceName !== null &&
+            sourceFile.sliceName !== null &&
+            !isCrossImportPublicApi(dependencyLocation.file, {
+              inSlice: dependencyLocation.sliceName,
+              forSlice: sourceFile.sliceName,
+              layerPath: join(root.path, dependencyLocation.layerName),
             })
-          } else {
+          ) {
             diagnostics.push({
               message: `Forbidden cross-import from slice "${dependencyLocation.sliceName}".`,
               location: { path: sourceFile.file.path },

packages/steiger-plugin-fsd/src/insignificant-slice/README.md

@@ -46,15 +46,20 @@ flowchart BT
   end
 
   subgraph entities
-    subgraph entities/user["user (only one reference)"]
+    subgraph entities/user["user (only one reference, @x doesn't count)"]
+      subgraph entities/user/at-x[@x]
+        entities/user/at-x/product.ts[product.ts]
+      end
       subgraph entities/user/ui[ui]
         entities/user/ui/UserAvatar.tsx[UserAvatar.tsx]
       end
       entities/user/index.ts[index.ts]
     end
 
     subgraph entities/product["product (no references)"]
-      entities/product/ui[ui]
+      subgraph entities/product/ui[ui]
+        entities/product/ui/ProductCard.tsx[ProductCard.tsx]
+      end
       entities/product/index.ts[index.ts]
     end
   end
@@ -72,13 +77,16 @@ flowchart BT
   shared/ui/Button.tsx --> shared/ui/styles.ts
   shared/ui/TextField.tsx --> shared/ui/styles.ts
   entities/user/ui/UserAvatar.tsx --> shared/ui/index.ts
+  entities/product/ui/ProductCard.tsx --> entities/user/at-x/product.ts
   pages/editor/ui/Editor.tsx --❗️--> entities/user/index.ts
   pages/editor/ui/EditorPage.tsx --> shared/ui/index.ts
   pages/editor/ui/EditorPage.tsx --> pages/editor/ui/Editor.tsx
 
   style entities/user fill:pink
   style entities/user/ui fill:pink
+  style entities/user/at-x fill:pink
   style entities/product fill:pink
+  style entities/product/ui fill:pink
 ```
 
 ## Rationale

packages/steiger-plugin-fsd/src/insignificant-slice/index.spec.ts

@@ -21,9 +21,11 @@ vi.mock('node:fs', async (importOriginal) => {
       '/shared/ui/Button.tsx': 'import styles from "./styles";',
       '/shared/ui/TextField.tsx': 'import styles from "./styles";',
       '/shared/ui/index.ts': '',
+      '/entities/user/@x/product.ts': '',
       '/entities/user/ui/UserAvatar.tsx': 'import { Button } from "@/shared/ui"',
       '/entities/user/index.ts': '',
       '/entities/product/ui/ProductCard.tsx': '',
+      '/entities/product/ui/CrossReferenceCard.tsx': 'import { UserAvatar } from "@/entities/user/@x/product"',
       '/entities/product/index.ts': '',
       '/features/comments/ui/CommentCard.tsx': '',
       '/features/comments/index.ts': '',
@@ -132,3 +134,36 @@ it('reports errors on a project with insignificant slices', async () => {
     },
   ])
 })
+
+it('reports errors on a project where the only other reference to a slice is a cross-import', async () => {
+  const root = parseIntoFsdRoot(`
+    📂 entities
+      📂 user
+        📂 @x
+          📄 product.ts
+        📂 ui
+          📄 UserAvatar.tsx
+        📄 index.ts
+      📂 product
+        📂 ui
+          📄 CrossReferenceCard.tsx
+        📄 index.ts
+    📂 pages
+      📂 editor
+        📂 ui
+          📄 EditorPage.tsx
+          📄 Editor.tsx
+        📄 index.ts
+  `)
+
+  expect((await insignificantSlice.check(root)).diagnostics.sort(compareMessages)).toEqual([
+    {
+      message: `This slice has no references. Consider removing it.`,
+      location: { path: joinFromRoot('entities', 'product') },
+    },
+    {
+      message: `This slice has only one reference in slice "${join('pages', 'editor')}". Consider merging them.`,
+      location: { path: joinFromRoot('entities', 'user') },
+    },
+  ])
+})

packages/steiger-plugin-fsd/src/insignificant-slice/index.ts

@@ -70,7 +70,7 @@ async function traceSliceReferences(root: Folder) {
         continue
       }
       const dependencyLocation = sourceFileIndex[resolvedDependency]
-      if (dependencyLocation === undefined) {
+      if (dependencyLocation === undefined || sourceFile.layerName === dependencyLocation.layerName) {
         continue
       }
 

packages/steiger-plugin-fsd/src/no-public-api-sidestep/README.md

@@ -7,6 +7,7 @@ Examples of imports that satisfy this rule:
 ```ts
 import { Button } from '@/shared/ui'
 import { UserAvatar } from '@/entities/user'
+import { UserAvatar } from '@/entities/user/@x/product'
 import { EditorPage } from '@/pages/editor'
 ```
 

packages/steiger-plugin-fsd/src/no-public-api-sidestep/index.spec.ts

@@ -20,9 +20,11 @@ vi.mock('node:fs', async (importOriginal) => {
       '/shared/ui/Button.tsx': 'import styles from "./styles";',
       '/shared/ui/TextField.tsx': 'import styles from "./styles";',
       '/shared/ui/index.ts': '',
+      '/entities/user/@x/product.ts': '',
       '/entities/user/ui/UserAvatar.tsx': 'import { Button } from "@/shared/ui"',
       '/entities/user/index.ts': '',
       '/entities/product/ui/ProductCard.tsx': 'import { UserAvatar } from "@/entities/user"',
+      '/entities/product/ui/CrossReferenceCard.tsx': 'import { UserAvatar } from "@/entities/user/@x/product"',
       '/entities/product/index.ts': '',
       '/features/comments/ui/CommentCard.tsx': 'import { styles } from "@/pages/editor"',
       '/features/comments/index.ts': '',
@@ -47,12 +49,15 @@ it('reports no errors on a project without public API sidesteps', async () => {
         📄 index.ts
     📂 entities
       📂 user
+        📂 @x
+          📄 product.ts
         📂 ui
           📄 UserAvatar.tsx
         📄 index.ts
       📂 product
         📂 ui
           📄 ProductCard.tsx
+          📄 CrossReferenceCard.tsx
         📄 index.ts
   `)
 

packages/steiger-plugin-fsd/src/no-public-api-sidestep/index.ts

@@ -2,7 +2,14 @@ import * as fs from 'node:fs'
 import precinct from 'precinct'
 const { paperwork } = precinct
 import { parse as parseNearestTsConfig } from 'tsconfck'
-import { getIndex, getLayers, getSegments, isSliced, resolveImport } from '@feature-sliced/filesystem'
+import {
+  getIndex,
+  getLayers,
+  getSegments,
+  isSliced,
+  resolveImport,
+  crossReferenceToken,
+} from '@feature-sliced/filesystem'
 import type { Folder, File, PartialDiagnostic, Rule } from '@steiger/types'
 
 import { indexSourceFiles } from '../_lib/index-source-files.js'
@@ -44,7 +51,7 @@ const noPublicApiSidestep = {
         }
 
         if (isSliced(dependencyLocation.layerName)) {
-          if (dependencyLocation.segmentName !== null) {
+          if (dependencyLocation.segmentName !== null && dependencyLocation.segmentName !== crossReferenceToken) {
             diagnostics.push({
               message: `Forbidden sidestep of public API when importing from "${dependency}".`,
               location: { path: sourceFile.file.path },

packages/steiger-plugin-fsd/src/no-reserved-folder-names/README.md

@@ -37,6 +37,8 @@ Examples of project structures that fail this rule:
     📄 index.ts
     📂 lib // ❌
       📄 someUiFunction.ts
+    📂 @x // ❌
+      📄 justForFun.ts
 📂 entities
   📂 user
     📂 ui

packages/steiger-plugin-fsd/src/no-reserved-folder-names/index.spec.ts

@@ -31,6 +31,8 @@ it('reports errors on a project with subfolders in segments that use reserved na
         📄 index.ts
         📂 lib
           📄 someUiFunction.ts
+        📂 @x
+          📄 justForFun.ts
     📂 entities
       📂 user
         📂 ui
@@ -49,5 +51,10 @@ it('reports errors on a project with subfolders in segments that use reserved na
         'Having a folder with the name "lib" inside a segment could be confusing because that name is commonly used for segments. Consider renaming it.',
       location: { path: joinFromRoot('shared', 'ui', 'lib') },
     },
+    {
+      message:
+        'Having a folder with the name "@x" inside a segment could be confusing because that name is reserved for cross-import public APIs. Consider renaming it.',
+      location: { path: joinFromRoot('shared', 'ui', '@x') },
+    },
   ])
 })