feat: add no-layer-public-api rule to prevent root-level public API files in layers

andrewmolyuk · andrewmolyuk · commit ed3c0d79ad4c · 2025-09-02T22:14:16.000+03:00
diff --git a/README.md b/README.md
@@ -62,13 +62,14 @@ module.exports = {
 
 The plugin provides the rules to enforce [Feature-Sliced Design](https://feature-sliced.design/) principles in [Vue.js](https://vuejs.org/) projects.
 
-| Rule                                                     | Description                                                               |
-| -------------------------------------------------------- | ------------------------------------------------------------------------- |
-| [fsd-layers](./docs/rules/fsd-layers.md)                 | Enforce consistent layer structure in feature-sliced design.              |
-| [no-processes-layer](./docs/rules/no-processes-layer.md) | Ensure deprecated processes layer is not used.                            |
-| [public-api](./docs/rules/public-api.md)                 | Enforce consistent public API structure in FSD slices.                    |
-| [sfc-sections-order](./docs/rules/sfc-sections-order.md) | Enforce consistent order of top-level sections in single-file components. |
-| [no-ui-in-app](./docs/rules/no-ui-in-app.md)             | Forbid placing `ui` segment directly inside the `app` layer.              |
+| Rule                                                       | Description                                                                            |
+| ---------------------------------------------------------- | -------------------------------------------------------------------------------------- |
+| [fsd-layers](./docs/rules/fsd-layers.md)                   | Enforce consistent layer structure in feature-sliced design.                           |
+| [no-processes-layer](./docs/rules/no-processes-layer.md)   | Ensure deprecated processes layer is not used.                                         |
+| [public-api](./docs/rules/public-api.md)                   | Enforce consistent public API structure in FSD slices.                                 |
+| [sfc-sections-order](./docs/rules/sfc-sections-order.md)   | Enforce consistent order of top-level sections in single-file components.              |
+| [no-ui-in-app](./docs/rules/no-ui-in-app.md)               | Forbid placing `ui` segment directly inside the `app` layer.                           |
+| [no-layer-public-api](./docs/rules/no-layer-public-api.md) | Forbid placing a layer-level public API file (e.g. `index.ts`) at the root of a layer. |
 
 ## Roadmap
 
diff --git a/docs/rules/no-layer-public-api.md b/docs/rules/no-layer-public-api.md
@@ -0,0 +1,64 @@
+# no-layer-public-api
+
+Disallow a layer-level public API file (for example `index.ts`) at the root of layers.
+
+## Why
+
+In a layered Feature-Sliced Design repository each top-level layer (for example `app`, `pages`, `widgets`, `entities`, etc.) should expose a public API at the slice level, not via a root-level `index` file inside the layer folder. Placing a root-level public API file can encourage leaking cross-layer imports and reduce encapsulation.
+
+This rule scans the configured `src` path and reports when a configured `filename` exists directly under a layer directory (for example `src/app/index.ts`). To keep noise low the rule reports at most once per linting session.
+
+## Rule details
+
+- Rule name: `vue-fsd/no-layer-public-api`
+- Default messageId: `forbidden`
+- Type: `problem`
+
+The rule checks each top-level directory inside the configured `src` for the presence of the configured `filename`. If a file with that name exists and is a regular file at the layer root, the rule reports once with a message pointing to the offending layer and filename.
+
+## Options
+
+The rule accepts a single options object with the following properties:
+
+- `src` (string) — the path or alias to your project's source root. Default: `"src"`.
+- `filename` (string) — the filename to treat as a layer-level public API. Default: `"index.ts"`.
+- `ignore` (string[]) — array of layer names to ignore (for example `['app']`). Default: `[]`.
+
+Example (ESLint config):
+
+```json
+{
+  "plugins": ["vue-fsd"],
+  "rules": {
+    "vue-fsd/no-layer-public-api": ["error", { "src": "src", "filename": "index.ts", "ignore": ["app"] }]
+  }
+}
+```
+
+## Examples
+
+Bad:
+
+```text
+// filesystem: src/app/index.ts
+src/app/index.ts        <-- reported
+src/app/page-a/index.ts <-- fine (slice-level public API)
+```
+
+Good:
+
+```text
+// keep public API at slice level only
+src/app/page-a/index.ts
+src/widgets/button/index.ts
+```
+
+## When not to use
+
+- When your project intentionally exposes a single root-level API for a layer (legacy codebases or libraries). Use the `ignore` option or set the rule to `off` during migration.
+- When the filename you want to detect differs from `index.ts` and you prefer another pattern — use the `filename` option.
+
+## References
+
+- [ESLint Documentation](https://eslint.org/docs/user-guide/configuring)
+- [Feature-Sliced Design](https://feature-sliced.design/)
diff --git a/src/configs.js b/src/configs.js
@@ -2,6 +2,7 @@ export const getConfigs = (plugin) => {
   const recommendedRules = {
     'vue-fsd/no-processes-layer': 'error',
     'vue-fsd/no-ui-in-app': 'error',
+    'vue-fsd/no-layer-public-api': 'error',
     'vue-fsd/sfc-sections-order': 'error',
     'vue-fsd/fsd-layers': 'error',
     'vue-fsd/public-api': 'error',
diff --git a/src/index.js b/src/index.js
@@ -4,6 +4,7 @@ import sfcSectionsOrder from './rules/sfc-sections-order.js'
 import fsdLayers from './rules/fsd-layers.js'
 import publicApi from './rules/public-api.js'
 import noUiInApp from './rules/no-ui-in-app.js'
+import noLayerPublicApi from './rules/no-layer-public-api.js'
 import { getConfigs } from './configs.js'
 
 const plugin = {
@@ -14,6 +15,7 @@ const plugin = {
     'fsd-layers': fsdLayers,
     'public-api': publicApi,
     'no-ui-in-app': noUiInApp,
+    'no-layer-public-api': noLayerPublicApi,
   },
   processors: {},
   configs: {},
diff --git a/src/rules/no-layer-public-api.js b/src/rules/no-layer-public-api.js
@@ -0,0 +1,84 @@
+import { runOnce, parseRuleOptions } from '../utils.js'
+import fs from 'fs'
+import path from 'path'
+
+const defaultOptions = {
+  src: 'src',
+  filename: 'index.ts',
+  ignore: [],
+}
+
+export default {
+  meta: {
+    type: 'problem',
+    docs: {
+      description: 'Forbid layer-level public API files (index.ts) at the root of layers.',
+      recommended: true,
+    },
+    schema: [
+      {
+        type: 'object',
+        properties: {
+          src: { type: 'string' },
+          filename: { type: 'string' },
+          ignore: { type: 'array', items: { type: 'string' } },
+        },
+        additionalProperties: false,
+      },
+    ],
+    defaultOptions: [defaultOptions],
+    messages: {
+      forbidden: 'Do not place a layer-level public API file "{{filename}}" inside layer "{{layer}}".',
+    },
+  },
+
+  create(context) {
+    const allowFsCheck = runOnce('no-layer-public-api')
+    const { src, filename, ignore } = parseRuleOptions(context, defaultOptions)
+
+    function isLayerDir(layerPath) {
+      try {
+        return fs.statSync(layerPath).isDirectory()
+      } catch {
+        return false
+      }
+    }
+
+    function checkIndexInLayer(entry, node) {
+      try {
+        const layerPath = path.join(src, entry)
+        if (!isLayerDir(layerPath)) return
+        if (Array.isArray(ignore) && ignore.includes(entry)) return
+
+        const indexPath = path.join(layerPath, filename)
+        if (!fs.existsSync(indexPath)) return
+
+        try {
+          const stat = fs.statSync(indexPath)
+          if (stat && typeof stat.isFile === 'function' && stat.isFile()) {
+            context.report({ node, messageId: 'forbidden', data: { layer: entry, filename } })
+          }
+        } catch {
+          // ignore stat errors on the index file
+        }
+      } catch {
+        // ignore errors per-entry
+      }
+    }
+
+    return {
+      Program(node) {
+        if (!allowFsCheck) return
+
+        try {
+          if (!fs.existsSync(src) || !fs.statSync(src).isDirectory()) return
+
+          const entries = fs.readdirSync(src)
+          for (const entry of entries) checkIndexInLayer(entry, node)
+        } catch {
+          // ignore filesystem errors
+        }
+      },
+    }
+  },
+}
diff --git a/test/rules/no-layer-public-api.test.js b/test/rules/no-layer-public-api.test.js
@@ -0,0 +1,173 @@
+import { describe, it, beforeEach, expect, vi } from 'vitest'
+import fs from 'fs'
+import path from 'path'
+import rule from '../../src/rules/no-layer-public-api.js'
+import { setupTest, runRule, createContext } from '../test-utils.js'
+
+describe('no-layer-public-api rule', () => {
+  beforeEach(setupTest)
+
+  it('does not report when no index.ts in layers', () => {
+    vi.spyOn(fs, 'readdirSync').mockReturnValue(['app', 'pages'])
+    vi.spyOn(fs, 'existsSync').mockReturnValue(false)
+
+    const ctx = runRule(rule)
+    expect(ctx.report).not.toHaveBeenCalled()
+  })
+
+  it('skips ignored entry early (covers ignore check)', () => {
+    vi.spyOn(fs, 'readdirSync').mockReturnValue(['app'])
+    vi.spyOn(fs, 'existsSync').mockImplementation((p) => {
+      if (p === 'src' || p.endsWith(path.sep + 'src')) return true
+      if (p.endsWith('index.ts')) return true
+      return false
+    })
+    vi.spyOn(fs, 'statSync').mockImplementation((p) => {
+      if (p === 'src' || p.endsWith(path.sep + 'src')) return { isDirectory: () => true }
+      if (p.endsWith(path.sep + 'app')) return { isDirectory: () => true }
+      return { isDirectory: () => false, isFile: () => false }
+    })
+
+    const ctx = createContext('file.js', [{ src: 'src', ignore: ['app'] }])
+    const res = runRule(rule, ctx)
+    expect(res.report).not.toHaveBeenCalled()
+  })
+
+  it('skips when index file is missing for a layer (covers existsSync check)', () => {
+    vi.spyOn(fs, 'readdirSync').mockReturnValue(['app'])
+    vi.spyOn(fs, 'existsSync').mockImplementation((p) => {
+      if (p === 'src' || p.endsWith(path.sep + 'src')) return true
+      return false
+    })
+    vi.spyOn(fs, 'statSync').mockImplementation((p) => {
+      if (p === 'src' || p.endsWith(path.sep + 'src')) return { isDirectory: () => true }
+      if (p.endsWith(path.sep + 'app')) return { isDirectory: () => true }
+      return { isDirectory: () => false, isFile: () => false }
+    })
+
+    const ctx = runRule(rule)
+    expect(ctx.report).not.toHaveBeenCalled()
+  })
+
+  it('reports when index.ts exists at layer root', () => {
+    vi.spyOn(fs, 'readdirSync').mockReturnValue(['app', 'pages'])
+    // Ensure src exists and index file exists
+    vi.spyOn(fs, 'existsSync').mockImplementation((p) => {
+      if (p.endsWith('index.ts')) return true
+      // treat src path as existing
+      if (p === 'src' || p.endsWith(path.sep + 'src')) return true
+      return false
+    })
+
+    vi.spyOn(fs, 'statSync').mockImplementation((p) => {
+      if (p === 'src' || p.endsWith(path.sep + 'src')) return { isDirectory: () => true }
+      if (p.endsWith(path.sep + 'app')) return { isDirectory: () => true }
+      if (p.endsWith('index.ts')) return { isFile: () => true }
+      return { isDirectory: () => false, isFile: () => false }
+    })
+
+    const ctx = runRule(rule)
+    expect(ctx.report).toHaveBeenCalledWith(expect.objectContaining({ messageId: 'forbidden' }))
+  })
+
+  it('respects ignore option', () => {
+    vi.spyOn(fs, 'readdirSync').mockReturnValue(['app', 'pages'])
+    vi.spyOn(fs, 'existsSync').mockImplementation((p) => p.endsWith('index.ts'))
+    vi.spyOn(fs, 'statSync').mockImplementation((p) => {
+      void p
+      return { isDirectory: () => true, isFile: () => true }
+    })
+
+    const ctx = createContext('file.js', [{ src: 'src', ignore: ['app'] }])
+    const res = runRule(rule, ctx)
+    expect(res.report).not.toHaveBeenCalled()
+  })
+
+  it('runs only once per session', () => {
+    vi.spyOn(fs, 'readdirSync').mockReturnValue(['app'])
+    vi.spyOn(fs, 'existsSync').mockReturnValue(true)
+    vi.spyOn(fs, 'statSync').mockImplementation((p) => {
+      void p
+      return { isDirectory: () => true, isFile: () => true }
+    })
+
+    const first = runRule(rule)
+    const second = runRule(rule)
+
+    expect(first.report).toHaveBeenCalled()
+    expect(second.report).not.toHaveBeenCalled()
+  })
+
+  it('ignores stat errors on the index file', () => {
+    vi.spyOn(fs, 'readdirSync').mockReturnValue(['app'])
+    vi.spyOn(fs, 'existsSync').mockImplementation((p) => {
+      if (p === 'src' || p.endsWith(path.sep + 'src')) return true
+      if (p.endsWith('index.ts')) return true
+      return false
+    })
+
+    vi.spyOn(fs, 'statSync').mockImplementation((p) => {
+      if (p === 'src' || p.endsWith(path.sep + 'src')) return { isDirectory: () => true }
+      if (p.endsWith(path.sep + 'app')) return { isDirectory: () => true }
+      // throw when trying to stat the index file
+      if (p.endsWith('index.ts')) throw new Error('stat failed')
+      return { isDirectory: () => false, isFile: () => false }
+    })
+
+    const ctx = runRule(rule)
+    expect(ctx.report).not.toHaveBeenCalled()
+  })
+
+  it('ignores errors from readdirSync', () => {
+    vi.spyOn(fs, 'existsSync').mockImplementation((p) => p === 'src' || p.endsWith(path.sep + 'src'))
+    vi.spyOn(fs, 'statSync').mockImplementation((p) => {
+      if (p === 'src' || p.endsWith(path.sep + 'src')) return { isDirectory: () => true }
+      return { isDirectory: () => false, isFile: () => false }
+    })
+
+    vi.spyOn(fs, 'readdirSync').mockImplementation(() => {
+      throw new Error('readdir failed')
+    })
+
+    const ctx = runRule(rule)
+    expect(ctx.report).not.toHaveBeenCalled()
+  })
+
+  it('ignores stat errors when checking the layer directory', () => {
+    vi.spyOn(fs, 'readdirSync').mockReturnValue(['app'])
+    vi.spyOn(fs, 'existsSync').mockImplementation((p) => {
+      if (p === 'src' || p.endsWith(path.sep + 'src')) return true
+      if (p.endsWith('index.ts')) return true
+      return false
+    })
+
+    vi.spyOn(fs, 'statSync').mockImplementation((p) => {
+      if (p === 'src' || p.endsWith(path.sep + 'src')) return { isDirectory: () => true }
+      // simulate stat throwing for the layer path
+      if (p.endsWith(path.sep + 'app')) throw new Error('layer stat failed')
+      if (p.endsWith('index.ts')) return { isFile: () => true }
+      return { isDirectory: () => false, isFile: () => false }
+    })
+
+    const ctx = runRule(rule)
+    expect(ctx.report).not.toHaveBeenCalled()
+  })
+
+  it('ignores errors thrown by existsSync when checking index path', () => {
+    vi.spyOn(fs, 'readdirSync').mockReturnValue(['app'])
+    vi.spyOn(fs, 'existsSync').mockImplementation((p) => {
+      if (p === 'src' || p.endsWith(path.sep + 'src')) return true
+      if (p.endsWith('index.ts')) throw new Error('exists failed')
+      return false
+    })
+
+    vi.spyOn(fs, 'statSync').mockImplementation((p) => {
+      if (p === 'src' || p.endsWith(path.sep + 'src')) return { isDirectory: () => true }
+      if (p.endsWith(path.sep + 'app')) return { isDirectory: () => true }
+      return { isDirectory: () => false, isFile: () => false }
+    })
+
+    const ctx = runRule(rule)
+    expect(ctx.report).not.toHaveBeenCalled()
+  })
+})
