feat: add feature-index-required rule to enforce public API entry file for features 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                                         | 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                                        | 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.        |
 
 ### Dependency Rules
 

docs/rules/feature-index-required.md

@@ -0,0 +1,89 @@
+# vue-modular/feature-index-required
+
+Require a public feature entry file (for example `src/features/<feature>/index.ts`) so consumers import from the feature root instead of deep-importing internal implementation files.
+
+## Rule Details
+
+This rule verifies that each feature folder exposes a public API index file. Keeping a small, stable public surface at the feature root helps encapsulate implementation details and makes refactors safer.
+
+By default the rule applies when the linted file path contains the configured `features` segment (default: `src/features`). If a feature contains implementation files but no supported index file exists, the rule reports a problem.
+
+Default index filename: `index.ts`, rule still accepts any filename via the `index` option.
+
+## Options
+
+The rule accepts an options object with the following properties:
+
+- `features` (string, default: `"src/features"`) — path segment used to detect the features root in file paths. If this segment is not present in the filename the rule ignores the file.
+- `ignore` (string[], default: `[]`) — array of feature-name patterns to skip. Patterns use `minimatch` semantics and are matched against the feature folder name (the single path segment after the features segment).
+- `index` (string, default: `"index.ts"`) — filename to look for as the feature public API. Use this to change the expected index file name (for example `index.js` or `main.ts`). The rule checks for this exact filename at the feature root.
+
+### Example configuration
+
+```js
+// Use defaults (scan `src/features` and no ignores)
+{
+  "vue-modular/feature-index-required": ["error"]
+}
+
+// Custom features folder and ignores
+{
+  "vue-modular/feature-index-required": [
+    "error",
+    { "features": "app/features", "ignore": ["shared-.*", "legacy"], "index": "main.ts" }
+  ]
+}
+```
+
+## Examples
+
+### Default index (index.ts)
+
+Incorrect (feature has files but no `index.ts`):
+
+```text
+// File: src/features/auth/components/LoginForm.vue
+// There is no src/features/auth/index.ts
+```
+
+Correct (add `index.ts` at feature root):
+
+```ts
+// File: src/features/auth/index.ts
+export * from './components'
+export * from './composables'
+```
+
+### Custom index filename (main.ts)
+
+If your project uses a different entry filename, configure `index` accordingly.
+
+Incorrect (rule configured with `index: 'main.ts'` but `main.ts` is missing):
+
+```text
+// File: app/features/auth/components/LoginForm.vue
+// There is no app/features/auth/main.ts (rule expects 'main.ts')
+```
+
+Correct (provide `main.ts` at feature root):
+
+```ts
+// File: app/features/auth/main.ts
+export * from './components'
+export * from './composables'
+```
+
+## Usage Notes
+
+- The rule executes a single scan per ESLint process (the plugin `runOnce` pattern) to avoid duplicate reports when linting multiple files.
+- The rule only reports when the inspected feature directory contains implementation files other than the configured index; empty folders or features fully covered by `ignore` are not reported.
+- The `ignore` option is matched against the feature folder name only (not the whole path) and uses `minimatch` semantics.
+- In monorepos or non-standard layouts, set the `features` option to an appropriate segment (for example `packages/*/src/features` or `app/features`) to avoid false positives.
+
+## When Not To Use
+
+- Do not enable this rule if your project intentionally relies on deep imports or follows a different public API strategy for features.
+
+## Further Reading
+
+- Modular design: prefer small public surfaces for modules/features to improve encapsulation and simplify refactors.

src/configs.js

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

src/index.js

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

src/rules/feature-index-required.js

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

tests/rules/feature-index-required.spec.js

@@ -0,0 +1,95 @@
+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/feature-index-required.js'
+
+const mockFileSystem = (hasIndex = true, indexFilename = 'index.ts') => {
+  // make existsSync return true for directories and conditionally for index files
+  vi.spyOn(fs, 'existsSync').mockImplementation((p) => {
+    const s = String(p)
+    // simulate feature folder path containing '/features/auth'
+    if (s.includes(`${path.sep}features${path.sep}auth`)) {
+      if (s.endsWith(indexFilename)) {
+        return hasIndex
+      }
+      return true
+    }
+    return false
+  })
+}
+
+describe('vue-modular/feature-index-required', () => {
+  beforeEach(setupTest)
+
+  it('reports when index.ts missing', () => {
+    mockFileSystem(false)
+    const filename = path.join(process.cwd(), 'src', 'features', 'auth', 'components', 'LoginForm.vue')
+    const ctx = runRule(rule, filename, [{ features: 'features', ignore: [] }])
+    expect(ctx.report).toHaveBeenCalled()
+  })
+
+  it('does not report when index.ts present', () => {
+    mockFileSystem(true)
+    const filename = path.join(process.cwd(), 'src', 'features', 'auth', 'components', 'LoginForm.vue')
+    const ctx = runRule(rule, filename, [{ features: 'features', ignore: [] }])
+    expect(ctx.report).not.toHaveBeenCalled()
+  })
+
+  it('runs only once per session', () => {
+    mockFileSystem(false)
+    const filename = path.join(process.cwd(), 'src', 'features', 'auth', 'components', 'LoginForm.vue')
+    const first = runRule(rule, filename, [{ features: 'features', ignore: [] }])
+    const second = runRule(rule, filename, [{ features: 'features', ignore: [] }])
+
+    expect(first.report).toHaveBeenCalled()
+    expect(second.report).not.toHaveBeenCalled()
+  })
+
+  it('does nothing for virtual filenames', () => {
+    mockFileSystem(false)
+    const ctx = runRule(rule, '<input>', [{ features: 'features', ignore: [] }])
+    expect(ctx.report).not.toHaveBeenCalled()
+  })
+
+  it('returns early when featureName missing (path ends with features)', () => {
+    mockFileSystem(false)
+    const filename = path.join(process.cwd(), 'src', 'features')
+    const ctx = runRule(rule, filename, [{ features: 'features', ignore: [] }])
+    expect(ctx.report).not.toHaveBeenCalled()
+  })
+
+  it('respects ignore option', () => {
+    mockFileSystem(false)
+    const filename = path.join(process.cwd(), 'src', 'features', 'auth', 'components', 'LoginForm.vue')
+    const ctx = runRule(rule, filename, [{ features: 'features', ignore: ['auth'] }])
+    expect(ctx.report).not.toHaveBeenCalled()
+  })
+
+  it('does nothing when configured features folder is not in filename path', () => {
+    mockFileSystem(false)
+    const filename = path.join(process.cwd(), 'src', 'other', 'auth', 'components', 'LoginForm.vue')
+    const ctx = runRule(rule, filename, [{ features: 'features', ignore: [] }])
+    expect(ctx.report).not.toHaveBeenCalled()
+  })
+
+  it('respects custom index filename option', () => {
+    // simulate that 'main.ts' is present and default index.ts is missing
+    mockFileSystem(true, 'main.ts')
+    const filename = path.join(process.cwd(), 'src', 'features', 'auth', 'components', 'LoginForm.vue')
+    // configure the rule to expect 'main.ts' as the feature index
+    const ctx = runRule(rule, filename, [{ features: 'features', ignore: [], index: 'main.ts' }])
+    // when main.ts exists, there should be no report
+    expect(ctx.report).not.toHaveBeenCalled()
+  })
+
+  it('reports when configured custom index is missing', () => {
+    // simulate that 'main.ts' is missing
+    mockFileSystem(false, 'main.ts')
+    const filename = path.join(process.cwd(), 'src', 'features', 'auth', 'components', 'LoginForm.vue')
+    // configure the rule to expect 'main.ts' as the feature index
+    const ctx = runRule(rule, filename, [{ features: 'features', ignore: [], index: 'main.ts' }])
+    // when main.ts does not exist, the rule should report
+    expect(ctx.report).toHaveBeenCalled()
+  })
+})