Merge pull request #12 from andrewmolyuk/components-index-required

andrewmolyuk · web-flow · commit adfd20d31a78 · 2025-09-11T23:04:35.000+03:00
feat: implement components-index-required rule to enforce index file in components directories
diff --git a/README.md b/README.md
@@ -107,18 +107,18 @@ This plugin provides rules to enforce modular architecture boundaries in Vue.js
 
 > The list of rules is a work in progress. Implemented rules are linked below; unimplemented rules are listed as plain names.
 >
-> ![Progress](https://progress-bar.xyz/5/?scale=92&width=500&title=5%20of%2092%20rules%20completed)
+> ![Progress](https://progress-bar.xyz/6/?scale=92&width=500&title=6%20of%2092%20rules%20completed)
 
 ### 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` (or configured filename) file for 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.                         |
+| 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](./docs/rules/shared-ui-index-required.md)   | The `shared/ui/` folder must contain an `index.ts` file for UI component exports.                         |
 
 ### Dependency Rules
 
diff --git a/docs/rules/components-index-required.md b/docs/rules/components-index-required.md
@@ -4,31 +4,32 @@ Enforce a components folder index file (for example `features/<feature>/componen
 
 ## 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.
+This rule scans the project's source tree (starting at the configured project `rootPath`, default: `src`) for `components` directories and verifies they contain 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.
+- `ignores` (string[], default: `[]`) — minimatch-style patterns matched against directory paths to skip certain folders from scanning.
 - `index` (string, default: `"index.ts"`) — filename to look for as the components public API (for example `index.js` or `main.ts`).
 
+Note: project-wide paths such as `rootPath` are read from plugin settings (`settings['vue-modular']`) and merged with defaults.
+
 ### Example configuration
 
 ```js
-// Use defaults (scan `components`, expect `index.ts`)
+// Use defaults (scan project src tree, expect `index.ts` in each components folder)
 {
   "vue-modular/components-index-required": ["error"]
 }
 
-// Custom configuration
+// Custom configuration (override index filename or add ignores)
 {
   "vue-modular/components-index-required": [
     "error",
-    { "components": "components", "ignore": ["shared"], "index": "main.ts" }
+    { "ignores": ["**/shared/**"], "index": "main.ts" }
   ]
 }
 ```
@@ -51,8 +52,7 @@ 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`).
+- Use the `ignores` option or update project `rootPath` via `settings['vue-modular']` when your repository places component folders in non-standard locations (for example monorepos).
 
 ## When Not To Use
 
diff --git a/src/rules/components-index-required.ts b/src/rules/components-index-required.ts
@@ -0,0 +1,69 @@
+import fs from 'fs'
+import path from 'path'
+import { parseRuleOptions, runOnce, createRule, isIgnored, parseProjectOptions } from '../utils'
+import type { VueModularRuleModule } from '../types'
+
+const defaultOptions = {
+  ignores: [],
+  index: 'index.ts',
+}
+
+export const componentsIndexRequired = createRule<VueModularRuleModule>({
+  create(context) {
+    if (!runOnce('components-index-required')) return {}
+
+    const options = parseRuleOptions(context, defaultOptions)
+    const projectOptions = parseProjectOptions(context)
+
+    return {
+      Program(node) {
+        try {
+          const dirs = fs
+            .readdirSync(projectOptions.rootPath, { recursive: true })
+            .filter((d) => fs.statSync(d).isDirectory())
+            .filter((d) => !isIgnored(String(d), options.ignores)) as string[]
+
+          dirs.forEach((dir) => {
+            const indexPath = path.join(dir, options.index)
+            const isExists = fs.existsSync(indexPath)
+
+            if (!isExists) {
+              context.report({
+                node,
+                messageId: 'missingIndex',
+                data: { indexPath: path.relative(process.cwd(), indexPath), index: options.index },
+              })
+            }
+          })
+        } catch {
+          // ignore fs errors
+        }
+      },
+    }
+  },
+  name: 'components-index-required',
+  recommended: true,
+  level: 'error',
+  meta: {
+    type: 'suggestion',
+    docs: {
+      description: 'Require a components/index.ts to expose the components public API',
+      category: 'File Organization',
+      recommended: false,
+    },
+    defaultOptions: [defaultOptions],
+    schema: [
+      {
+        type: 'object',
+        properties: {
+          ignores: { type: 'array', items: { type: 'string' } },
+          index: { type: 'string' },
+        },
+        additionalProperties: false,
+      },
+    ],
+    messages: {
+      missingIndex: "Components folder is missing a public API file '{{indexPath}}'. Add '{{index}}' to expose the component public API.",
+    },
+  },
+})
diff --git a/tests/rules/components-index-required.test.ts b/tests/rules/components-index-required.test.ts
@@ -0,0 +1,76 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest'
+import { runRule, setupTest } from '../test-utils'
+import { componentsIndexRequired } from '../../src/rules/components-index-required'
+import fs from 'fs'
+
+describe('components-index-required rule', () => {
+  beforeEach(() => setupTest())
+
+  it('reports a missing index file for a components directory that has files but no index', () => {
+    vi.spyOn(fs, 'readdirSync').mockReturnValue(['components-without-index', 'components-with-index'] as unknown as fs.Dirent<
+      Buffer<ArrayBufferLike>
+    >[])
+    vi.spyOn(fs, 'statSync').mockReturnValue({ isDirectory: () => true } as unknown as fs.Stats)
+    vi.spyOn(fs, 'existsSync').mockImplementation((p) => String(p).includes('components-with-index'))
+
+    const context = runRule(componentsIndexRequired, 'filename.ts')
+
+    expect(context.report).toHaveBeenCalledTimes(1)
+    expect(context.report).toHaveBeenCalledWith(
+      expect.objectContaining({
+        messageId: 'missingIndex',
+        data: expect.objectContaining({ indexPath: 'components-without-index/index.ts', index: 'index.ts' }),
+      }),
+    )
+  })
+
+  it('does not report when every components directory contains the expected index file', () => {
+    vi.spyOn(fs, 'readdirSync').mockReturnValue(['components-a', 'components-b'] as unknown as fs.Dirent<Buffer<ArrayBufferLike>>[])
+    vi.spyOn(fs, 'statSync').mockReturnValue({ isDirectory: () => true } as unknown as fs.Stats)
+    vi.spyOn(fs, 'existsSync').mockReturnValue(true)
+
+    const context = runRule(componentsIndexRequired, 'filename.ts')
+
+    expect(context.report).not.toHaveBeenCalled()
+  })
+
+  it('respects ignore option and does not report for ignored components dirs', () => {
+    vi.spyOn(fs, 'readdirSync').mockReturnValue(['ignored-components', 'normal-components'] as unknown as fs.Dirent<
+      Buffer<ArrayBufferLike>
+    >[])
+    vi.spyOn(fs, 'statSync').mockReturnValue({ isDirectory: () => true } as unknown as fs.Stats)
+    vi.spyOn(fs, 'existsSync').mockReturnValue(false)
+
+    const context = runRule(componentsIndexRequired, 'filename.ts', [{ ignores: ['ignored-components'], index: 'index.ts' }])
+
+    expect(context.report).toHaveBeenCalledTimes(1)
+    expect(context.report).toHaveBeenCalledWith(
+      expect.objectContaining({
+        messageId: 'missingIndex',
+        data: expect.objectContaining({ indexPath: 'normal-components/index.ts', index: 'index.ts' }),
+      }),
+    )
+  })
+
+  it('does nothing when runOnce returns false', () => {
+    vi.spyOn(fs, 'readdirSync').mockReturnValue(['components-without-index'] as unknown as fs.Dirent<Buffer<ArrayBufferLike>>[])
+    vi.spyOn(fs, 'statSync').mockReturnValue({ isDirectory: () => true } as unknown as fs.Stats)
+    vi.spyOn(fs, 'existsSync').mockReturnValue(false)
+
+    const context1 = runRule(componentsIndexRequired, 'filename1.ts')
+    const context2 = runRule(componentsIndexRequired, 'filename2.ts')
+
+    expect(context1.report).toHaveBeenCalledTimes(1)
+    expect(context2.report).not.toHaveBeenCalled()
+  })
+
+  it('handles fs errors gracefully (does not throw)', () => {
+    vi.spyOn(fs, 'readdirSync').mockImplementation(() => {
+      throw new Error('boom')
+    })
+
+    expect(() => {
+      runRule(componentsIndexRequired, 'filename.ts')
+    }).not.toThrow()
+  })
+})
