feat: add components-index-required rule to enforce components folder index file and implement related tests

Author: andrewmolyuk

README.md

@@ -88,14 +88,14 @@ This plugin provides rules to enforce modular architecture boundaries in Vue.js
 
 ### File Organization Rules
 
-| Rule                                                             | Description                                                                              |
-| ---------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
-| [file-component-naming](./docs/rules/file-component-naming.md)   | All Vue components must use PascalCase naming (e.g., `UserForm.vue`, `ProductList.vue`). |
-| [file-ts-naming](./docs/rules/file-ts-naming.md)                 | All TypeScript files must use camelCase naming (e.g., `useAuth.ts`, `userApi.ts`).       |
-| [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                                        | All `components/` folders must contain an `index.ts` file for component exports.         |
-| shared-ui-index-required                                         | The `shared/ui/` folder must contain an `index.ts` file for UI component exports.        |
+| Rule                                                                   | Description                                                                                               |
+| ---------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
+| [file-component-naming](./docs/rules/file-component-naming.md)         | All Vue components must use PascalCase naming (e.g., `UserForm.vue`, `ProductList.vue`).                  |
+| [file-ts-naming](./docs/rules/file-ts-naming.md)                       | All TypeScript files must use camelCase naming (e.g., `useAuth.ts`, `userApi.ts`).                        |
+| [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.                         |
 
 ### Dependency Rules
 

docs/rules/components-index-required.md

@@ -0,0 +1,63 @@
+# vue-modular/components-index-required
+
+Enforce a components folder index file (for example `features/<feature>/components/index.ts`) so component consumers import from the components root instead of deep-importing implementation files.
+
+## Rule Details
+
+This rule verifies that a `components` directory inside a feature (or any configured segment) exposes a public API file. A stable components index makes imports shorter, centralizes re-exports, and reduces accidental deep imports.
+
+Default index filename: `index.ts`.
+
+## Options
+
+The rule accepts an options object with the following properties:
+
+- `components` (string, default: `"components"`) — the path segment used to locate component directories under a feature.
+- `ignore` (string[], default: `[]`) — minimatch-style patterns matched against the parent folder name to skip certain features.
+- `index` (string, default: `"index.ts"`) — filename to look for as the components public API (for example `index.js` or `main.ts`).
+
+### Example configuration
+
+```js
+// Use defaults (scan `components`, expect `index.ts`)
+{
+  "vue-modular/components-index-required": ["error"]
+}
+
+// Custom configuration
+{
+  "vue-modular/components-index-required": [
+    "error",
+    { "components": "components", "ignore": ["shared"], "index": "main.ts" }
+  ]
+}
+```
+
+## Incorrect
+
+```text
+// File: src/features/auth/components/Button.vue
+// There is no src/features/auth/components/index.ts
+```
+
+## Correct
+
+```ts
+// File: src/features/auth/components/index.ts
+export { default as Button } from './Button.vue'
+export { default as Icon } from './Icon.vue'
+```
+
+## Usage Notes
+
+- The rule executes a single scan per ESLint process using the plugin's `runOnce` utility — this avoids duplicate reports when linting many files.
+- The `ignore` option matches against the feature (parent) folder name and uses `minimatch` semantics.
+- If your repository places component folders at non-standard locations, change the `components` option (for example `shared/components` or `app/components`).
+
+## When Not To Use
+
+- Do not enable this rule if your project intentionally relies on deep imports or uses a different component export strategy.
+
+## Further Reading
+
+- Centralized re-exports and module boundaries help reduce coupling and improve refactorability.

src/configs.js

@@ -3,6 +3,7 @@ const recommendedRules = {
   'vue-modular/file-ts-naming': 'error',
   'vue-modular/folder-kebab-case': 'error',
   'vue-modular/feature-index-required': 'error',
+  'vue-modular/components-index-required': 'error',
 }
 
 const allRules = {

src/index.js

@@ -5,6 +5,7 @@ import fileComponentNaming from './rules/file-component-naming.js'
 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'
 
 const plugin = {
   meta,
@@ -13,6 +14,7 @@ const plugin = {
     'file-ts-naming': fileTsNaming,
     'folder-kebab-case': folderKebabCase,
     'feature-index-required': featureIndexRequired,
+    'components-index-required': componentsIndexRequired,
   },
   processors: {},
   configs: {},

src/rules/components-index-required.js

@@ -0,0 +1,70 @@
+/**
+ * @fileoverview Require components/{parent}/index.ts public API file
+ */
+
+import fs from 'fs'
+import path from 'path'
+import { parseRuleOptions, isFileIgnored, runOnce } from '../utils.js'
+
+const defaultOptions = {
+  components: 'components',
+  ignore: [],
+  index: 'index.ts',
+}
+
+export default {
+  meta: {
+    type: 'suggestion',
+    docs: {
+      description: 'Require a components public API file components/{parent}/index.ts when a components folder contains files',
+      category: 'Best Practices',
+      recommended: false,
+    },
+    defaultOptions: [defaultOptions],
+    schema: [
+      {
+        type: 'object',
+        properties: {
+          components: { type: 'string' },
+          ignore: { type: 'array', items: { type: 'string' } },
+          index: { type: 'string' },
+        },
+        additionalProperties: false,
+      },
+    ],
+    messages: {
+      missingIndex:
+        "Components folder '{{parent}}' is missing a public API file '{{indexPath}}' (expected '{{index}}'). Add '{{index}}' to expose the components public API.",
+    },
+  },
+
+  create(context) {
+    const { components, ignore, index } = parseRuleOptions(context, defaultOptions)
+
+    return {
+      Program(node) {
+        if (!runOnce('vue-modular/components-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(components)
+        if (idx === -1) return
+
+        const parentName = parts[idx - 1]
+        if (!parentName) return
+        if (isFileIgnored(parentName, ignore)) return
+
+        const componentsKey = parts.slice(0, idx + 1).join(path.sep)
+        const indexPath = path.join(componentsKey, index)
+        const exists = fs.existsSync(indexPath)
+
+        if (!exists) {
+          context.report({ node, messageId: 'missingIndex', data: { parent: parentName, indexPath, index } })
+        }
+      },
+    }
+  },
+}

tests/rules/components-index-required.test.js

@@ -0,0 +1,86 @@
+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/components-index-required.js'
+
+const mockFileSystem = (hasIndex = true, indexFilename = 'index.ts') => {
+  vi.spyOn(fs, 'existsSync').mockImplementation((p) => {
+    const s = String(p)
+    // simulate components folder path containing '/features/<feature>/components'
+    if (
+      s.includes(`${path.sep}features${path.sep}auth${path.sep}components`) ||
+      s.includes(`${path.sep}features${path.sep}shared${path.sep}components`)
+    ) {
+      if (s.endsWith(indexFilename)) {
+        return hasIndex
+      }
+      return true
+    }
+    return false
+  })
+}
+
+describe('vue-modular/components-index-required', () => {
+  beforeEach(setupTest)
+
+  it('reports when index.ts missing for components folder', () => {
+    mockFileSystem(false)
+    const filename = path.join(process.cwd(), 'src', 'features', 'auth', 'components', 'Button.vue')
+    const ctx = runRule(rule, filename, [{ components: 'components', ignore: [] }])
+    expect(ctx.report).toHaveBeenCalled()
+  })
+
+  it('returns early when parentName missing (components at path start)', () => {
+    mockFileSystem(false)
+    // relative filename with components as the first segment -> parentName undefined
+    const filename = path.join('components', 'Button.vue')
+    const ctx = runRule(rule, filename, [{ components: 'components', ignore: [] }])
+    expect(ctx.report).not.toHaveBeenCalled()
+  })
+
+  it('runs only once per session', () => {
+    mockFileSystem(false)
+    const filename = path.join(process.cwd(), 'src', 'features', 'auth', 'components', 'Button.vue')
+    const first = runRule(rule, filename, [{ components: 'components', ignore: [] }])
+    const second = runRule(rule, filename, [{ components: 'components', ignore: [] }])
+
+    expect(first.report).toHaveBeenCalled()
+    expect(second.report).not.toHaveBeenCalled()
+  })
+
+  it('does not report when index.ts present for components folder', () => {
+    mockFileSystem(true)
+    const filename = path.join(process.cwd(), 'src', 'features', 'auth', 'components', 'Button.vue')
+    const ctx = runRule(rule, filename, [{ components: 'components', ignore: [] }])
+    expect(ctx.report).not.toHaveBeenCalled()
+  })
+
+  it('respects ignore option', () => {
+    mockFileSystem(false)
+    const filename = path.join(process.cwd(), 'src', 'features', 'shared', 'components', 'Icon.vue')
+    const ctx = runRule(rule, filename, [{ components: 'components', ignore: ['shared'] }])
+    expect(ctx.report).not.toHaveBeenCalled()
+  })
+
+  it('does nothing for virtual filenames', () => {
+    mockFileSystem(false)
+    const ctx = runRule(rule, '<input>', [{ components: 'components', ignore: [] }])
+    expect(ctx.report).not.toHaveBeenCalled()
+  })
+
+  it('does nothing when configured components folder is not in filename path', () => {
+    mockFileSystem(false)
+    const filename = path.join(process.cwd(), 'src', 'other', 'auth', 'components', 'Button.vue')
+    // configure the rule to look for a components segment that doesn't exist in the path
+    const ctx = runRule(rule, filename, [{ components: 'no-components-here', ignore: [] }])
+    expect(ctx.report).not.toHaveBeenCalled()
+  })
+
+  it('supports custom index filename', () => {
+    mockFileSystem(true, 'main.ts')
+    const filename = path.join(process.cwd(), 'src', 'features', 'auth', 'components', 'Button.vue')
+    const ctx = runRule(rule, filename, [{ components: 'components', ignore: [], index: 'main.ts' }])
+    expect(ctx.report).not.toHaveBeenCalled()
+  })
+})