feat!: add shared-ui-index-required rule to enforce shared/ui public API file and implement related documentation and tests

Author: andrewmolyuk

README.md

@@ -95,7 +95,7 @@ This plugin provides rules to enforce modular architecture boundaries in Vue.js
 | [folder-kebab-case](./docs/rules/folder-kebab-case.md)                 | All folders must use kebab-case naming (e.g., `user-management/`, `auth/`).                               |
 | [feature-index-required](./docs/rules/feature-index-required.md)       | Each feature folder must contain an `index.ts` file as its public API.                                    |
 | [components-index-required](./docs/rules/components-index-required.md) | All `components/` folders must contain an `index.ts` (or configured filename) file for component exports. |
-| shared-ui-index-required                                               | The `shared/ui/` folder must contain an `index.ts` file for UI component exports.                         |
+| [shared-ui-index-required](./docs/rules/shared-ui-index-required.md)   | The `shared/ui/` folder must contain an `index.ts` file for UI component exports.                         |
 
 ### Dependency Rules
 

docs/rules/shared-ui-index-required.md

@@ -0,0 +1,58 @@
+# vue-modular/shared-ui-index-required
+
+Require a `shared/ui` public API file (for example `shared/ui/index.ts`) so shared UI components are exported from a single, stable entry point.
+
+## Rule Details
+
+This rule verifies that a `shared/ui` directory contains a public API file. A central entry file shortens imports, centralizes re-exports, and prevents consumers from deep-importing component implementation files.
+
+The rule only inspects files whose path contains the configured `shared` segment (default: `shared`). If a `shared/ui` folder contains implementation files but the configured index file is missing, the rule reports a problem.
+
+Default index filename: `index.ts`.
+
+## Options
+
+The rule accepts an options object with the following properties:
+
+- `shared` (string, default: `"shared"`) — path segment used to locate the shared folder in file paths.
+- `index` (string, default: `"index.ts"`) — filename to look for as the shared UI public API. Change this if your project uses a different entry filename (for example `main.ts`).
+
+### Example configuration
+
+```js
+{
+  "vue-modular/shared-ui-index-required": [
+    "error",
+    { "shared": "shared", "index": "index.ts" }
+  ]
+}
+```
+
+## Examples
+
+Incorrect
+
+```text
+// File: src/shared/ui/Button.vue
+// There is no src/shared/ui/index.ts
+```
+
+Correct
+
+```ts
+// File: src/shared/ui/index.ts
+export { default as Button } from './Button.vue'
+```
+
+## Usage Notes
+
+- The rule uses the plugin `runOnce` pattern to emit a single report per ESLint process, avoiding duplicate reports when linting many files.
+- In monorepos or non-standard layouts, set the `shared` option to the appropriate path segment (for example `packages/*/shared`) to avoid false positives.
+
+## When Not To Use
+
+- Do not enable this rule if your project intentionally relies on deep imports from `shared/ui` or uses a different export strategy.
+
+## Further Reading
+
+- Centralized re-exports and small public surfaces help reduce coupling and make refactors safer.

src/configs.js

@@ -4,6 +4,7 @@ const recommendedRules = {
   'vue-modular/folder-kebab-case': 'error',
   'vue-modular/feature-index-required': 'error',
   'vue-modular/components-index-required': 'error',
+  'vue-modular/shared-ui-index-required': 'error',
 }
 
 const allRules = {

src/index.js

@@ -6,6 +6,7 @@ import fileTsNaming from './rules/file-ts-naming.js'
 import folderKebabCase from './rules/folder-kebab-case.js'
 import featureIndexRequired from './rules/feature-index-required.js'
 import componentsIndexRequired from './rules/components-index-required.js'
+import sharedUiIndexRequired from './rules/shared-ui-index-required.js'
 
 const plugin = {
   meta,
@@ -15,6 +16,7 @@ const plugin = {
     'folder-kebab-case': folderKebabCase,
     'feature-index-required': featureIndexRequired,
     'components-index-required': componentsIndexRequired,
+    'shared-ui-index-required': sharedUiIndexRequired,
   },
   processors: {},
   configs: {},

src/rules/components-index-required.js

@@ -1,7 +1,3 @@
-/**
- * @fileoverview Require components/{parent}/index.ts public API file
- */
-
 import fs from 'fs'
 import path from 'path'
 import { parseRuleOptions, isFileIgnored, runOnce } from '../utils.js'

src/rules/feature-index-required.js

@@ -1,7 +1,3 @@
-/**
- * @fileoverview Require features/{feature}/index.ts public API file
- */
-
 import fs from 'fs'
 import path from 'path'
 import { parseRuleOptions, isFileIgnored, runOnce } from '../utils.js'

src/rules/shared-ui-index-required.js

@@ -0,0 +1,63 @@
+import fs from 'fs'
+import path from 'path'
+import { parseRuleOptions, runOnce } from '../utils.js'
+
+const defaultOptions = {
+  shared: 'shared',
+  index: 'index.ts',
+}
+
+export default {
+  meta: {
+    type: 'suggestion',
+    docs: {
+      description: 'Require a shared/ui public API file shared/ui/index.ts when UI components exist',
+      category: 'Best Practices',
+      recommended: false,
+    },
+    defaultOptions: [defaultOptions],
+    schema: [
+      {
+        type: 'object',
+        properties: {
+          shared: { type: 'string' },
+          index: { type: 'string' },
+        },
+        additionalProperties: false,
+      },
+    ],
+    messages: {
+      missingIndex:
+        "Shared UI folder is missing a public API file '{{indexPath}}' (expected '{{index}}'). Add '{{index}}' to expose shared UI components.",
+    },
+  },
+
+  create(context) {
+    const { shared, index } = parseRuleOptions(context, defaultOptions)
+
+    return {
+      Program(node) {
+        if (!runOnce('vue-modular/shared-ui-index-required')) return
+
+        const filename = context.getFilename()
+        if (!filename || filename === '<input>' || filename === '<text>') return
+
+        const normalized = path.normalize(filename)
+        const parts = normalized.split(path.sep)
+        const idx = parts.lastIndexOf(shared)
+        if (idx === -1) return
+
+        // expect the next segment to be 'ui'
+        if (parts[idx + 1] !== 'ui') return
+
+        const sharedUiKey = parts.slice(0, idx + 2).join(path.sep)
+        const indexPath = path.join(sharedUiKey, index)
+        const exists = fs.existsSync(indexPath)
+
+        if (!exists) {
+          context.report({ node, messageId: 'missingIndex', data: { indexPath, index } })
+        }
+      },
+    }
+  },
+}

tests/rules/shared-ui-index-required.test.js

@@ -0,0 +1,65 @@
+import fs from 'fs'
+import path from 'path'
+import { describe, it, expect, beforeEach, vi } from 'vitest'
+import { setupTest, runRule } from '../utils.js'
+import rule from '../../src/rules/shared-ui-index-required.js'
+
+const mockFileSystem = (hasIndex = true, indexFilename = 'index.ts') => {
+  vi.spyOn(fs, 'existsSync').mockImplementation((p) => {
+    const s = String(p)
+    // simulate shared/ui path: '/shared/ui'
+    if (s.includes(`${path.sep}shared${path.sep}ui`)) {
+      if (s.endsWith(indexFilename)) return hasIndex
+      return true
+    }
+    return false
+  })
+}
+
+describe('vue-modular/shared-ui-index-required', () => {
+  beforeEach(setupTest)
+
+  it('reports when shared/ui index missing', () => {
+    mockFileSystem(false)
+    const filename = path.join(process.cwd(), 'src', 'shared', 'ui', 'Button.vue')
+    const ctx = runRule(rule, filename, [{ shared: 'shared', index: 'index.ts' }])
+    expect(ctx.report).toHaveBeenCalled()
+  })
+
+  it('does not report when shared/ui index present', () => {
+    mockFileSystem(true)
+    const filename = path.join(process.cwd(), 'src', 'shared', 'ui', 'Button.vue')
+    const ctx = runRule(rule, filename, [{ shared: 'shared', index: 'index.ts' }])
+    expect(ctx.report).not.toHaveBeenCalled()
+  })
+
+  it('does nothing when not under shared/ui', () => {
+    mockFileSystem(false)
+    const filename = path.join(process.cwd(), 'src', 'shared', 'components', 'Button.vue')
+    const ctx = runRule(rule, filename, [{ shared: 'shared', index: 'index.ts' }])
+    expect(ctx.report).not.toHaveBeenCalled()
+  })
+
+  it('does nothing when configured shared segment is not in filename path', () => {
+    mockFileSystem(false)
+    const filename = path.join(process.cwd(), 'src', 'features', 'auth', 'ui', 'Button.vue')
+    const ctx = runRule(rule, filename, [{ shared: 'shared', index: 'index.ts' }])
+    expect(ctx.report).not.toHaveBeenCalled()
+  })
+
+  it('runs only once per session', () => {
+    mockFileSystem(false)
+    const filename = path.join(process.cwd(), 'src', 'shared', 'ui', 'Button.vue')
+    const first = runRule(rule, filename, [{ shared: 'shared', index: 'index.ts' }])
+    const second = runRule(rule, filename, [{ shared: 'shared', index: 'index.ts' }])
+
+    expect(first.report).toHaveBeenCalled()
+    expect(second.report).not.toHaveBeenCalled()
+  })
+
+  it('does nothing for virtual filenames', () => {
+    mockFileSystem(false)
+    const ctx = runRule(rule, '<input>', [{ shared: 'shared', index: 'index.ts' }])
+    expect(ctx.report).not.toHaveBeenCalled()
+  })
+})