feat: add no-direct-feature-imports rule to enforce encapsulation between feature folders and implement related documentation and tests

andrewmolyuk · andrewmolyuk · commit fe012ade8608 · 2025-09-04T23:44:39.000+03:00
BREAKING CHANGE: we remodeled project structure and rules from the scratch
diff --git a/README.md b/README.md
@@ -99,13 +99,13 @@ This plugin provides rules to enforce modular architecture boundaries in Vue.js
 
 ### Dependency Rules
 
-| Rule                             | Description                                                                                                                                       |
-| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
-| no-direct-feature-imports        | Features cannot import from other features directly.                                                                                              |
-| feature-imports-from-shared-only | Features can only import from `shared/` folder.                                                                                                   |
-| no-shared-imports-from-features  | `shared/` folder cannot import from `features/` or `views/`.                                                                                      |
-| app-imports                      | `app/` folder can import from `shared/` and `features/` (exception: `app/router.ts` may import feature route files to compose the global router). |
-| cross-feature-via-shared         | All cross-feature communication must go through the `shared/` layer.                                                                              |
+| Rule                                                                   | Description                                                                                                                                       |
+| ---------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [no-direct-feature-imports](./docs/rules/no-direct-feature-imports.md) | Features cannot import from other features directly.                                                                                              |
+| feature-imports-from-shared-only                                       | Features can only import from `shared/` folder.                                                                                                   |
+| no-shared-imports-from-features                                        | `shared/` folder cannot import from `features/` or `views/`.                                                                                      |
+| app-imports                                                            | `app/` folder can import from `shared/` and `features/` (exception: `app/router.ts` may import feature route files to compose the global router). |
+| cross-feature-via-shared                                               | All cross-feature communication must go through the `shared/` layer.                                                                              |
 
 ### Component Rules
 
diff --git a/docs/rules/no-direct-feature-imports.md b/docs/rules/no-direct-feature-imports.md
@@ -0,0 +1,63 @@
+# vue-modular/no-direct-feature-imports
+
+Disallow direct imports between feature folders. Cross-feature communication should go through the feature public API or the `shared/` layer to preserve encapsulation.
+
+## Rule Details
+
+This rule detects imports that reference another feature's implementation files directly (for example `src/features/payments/utils/api.js`) from inside a different feature. Direct cross-feature imports increase coupling and make refactors harder because consumers can depend on internal implementation details.
+
+By default the rule considers file paths that contain the configured `features` segment (default: `src/features`) as feature sources to inspect. Import specifiers are resolved and analyzed; relative imports are resolved against the current file so `../../payments/...` correctly identifies the `payments` feature.
+
+The rule ignores virtual filenames (`<input>`, `<text>`) and test files (files matched by the project's test detection utility). It also accepts an `ignore` option to skip reporting for specific target feature names.
+
+## 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).
+
+### Example configuration
+
+```js
+// Use defaults (scan `src/features` and no ignores)
+{
+  "vue-modular/no-direct-feature-imports": ["error"]
+}
+
+// Ignore a legacy feature
+{
+  "vue-modular/no-direct-feature-imports": [
+    "error",
+    { "features": "app/features", "ignore": ["legacy", "payments-stub"] }
+  ]
+}
+```
+
+## Examples
+
+Incorrect (direct import from another feature):
+
+```text
+// File: src/features/auth/components/LoginForm.vue
+import { charge } from '../../payments/utils/api.js' // -> imports implementation from another feature
+```
+
+Correct (use feature public API or shared layer):
+
+```ts
+// File: src/features/auth/components/LoginForm.vue
+import { charge } from 'features/payments' // public API at src/features/payments/index.ts
+// or
+import { charge } from 'shared/services/paymentClient' // shared layer
+```
+
+## Notes
+
+- The rule resolves relative import paths against the linted file to correctly map `..` segments to absolute filesystem paths.
+- Test files and virtual filenames are ignored to avoid false positives during tests and non-file sources.
+- Use the `ignore` option to whitelist feature names that should not be reported.
+
+## When Not To Use
+
+- Disable this rule if your project intentionally allows deep cross-feature imports or during migration phases where you need temporary exceptions.
diff --git a/src/configs.js b/src/configs.js
@@ -5,6 +5,7 @@ const recommendedRules = {
   'vue-modular/feature-index-required': 'error',
   'vue-modular/components-index-required': 'error',
   'vue-modular/shared-ui-index-required': 'error',
+  'vue-modular/no-direct-feature-imports': 'error',
 }
 
 const allRules = {
diff --git a/src/index.js b/src/index.js
@@ -7,6 +7,7 @@ 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'
+import noDirectFeatureImports from './rules/no-direct-feature-imports.js'
 
 const plugin = {
   meta,
@@ -17,6 +18,7 @@ const plugin = {
     'feature-index-required': featureIndexRequired,
     'components-index-required': componentsIndexRequired,
     'shared-ui-index-required': sharedUiIndexRequired,
+    'no-direct-feature-imports': noDirectFeatureImports,
   },
   processors: {},
   configs: {},
diff --git a/src/rules/no-direct-feature-imports.js b/src/rules/no-direct-feature-imports.js
@@ -0,0 +1,99 @@
+import path from 'path'
+import { parseRuleOptions, isTestFile, isFileIgnored } from '../utils.js'
+
+const defaultOptions = {
+  features: 'src/features',
+  ignore: [],
+}
+
+export default {
+  meta: {
+    type: 'problem',
+    docs: {
+      description: 'Disallow direct imports from other feature folders (use shared layer or feature public API)',
+      category: 'Best Practices',
+      recommended: false,
+    },
+    defaultOptions: [defaultOptions],
+    schema: [
+      {
+        type: 'object',
+        properties: {
+          features: { type: 'string' },
+          ignore: { type: 'array', items: { type: 'string' } },
+        },
+        additionalProperties: false,
+      },
+    ],
+    messages: {
+      forbidden:
+        "Direct import from another feature '{{targetFeature}}' is not allowed. Import from the feature public API or from 'shared/'.",
+    },
+  },
+
+  create(context) {
+    const { features, ignore } = parseRuleOptions(context, defaultOptions)
+
+    return {
+      Program() {
+        // compute per-file context needed by ImportDeclaration visitor
+        const filename = context.getFilename()
+        if (!filename || filename === '<input>' || filename === '<text>') {
+          // mark as no-op
+          context.__noDirectFeatureSource = null
+          return
+        }
+        if (isTestFile(filename)) {
+          context.__noDirectFeatureSource = null
+          return
+        }
+
+        const normalized = path.normalize(filename)
+        const parts = normalized.split(path.sep)
+        const featuresIdx = parts.lastIndexOf(features)
+        if (featuresIdx === -1) {
+          context.__noDirectFeatureSource = null
+          return
+        }
+
+        const sourceFeature = parts[featuresIdx + 1]
+        if (!sourceFeature) {
+          context.__noDirectFeatureSource = null
+          return
+        }
+
+        // store sourceFeature and filename on context for ImportDeclaration to use
+        context.__noDirectFeatureSource = { sourceFeature, filename }
+      },
+
+      ImportDeclaration(node) {
+        const state = context.__noDirectFeatureSource
+        if (!state) return
+
+        const { sourceFeature, filename } = state
+        const spec = node && node.source && node.source.value
+        if (!spec || typeof spec !== 'string') return
+
+        // Resolve relative imports against the current file so './utils' -> absolute path
+        let impPath = spec
+        if (impPath.startsWith('.')) {
+          impPath = path.join(path.dirname(filename), impPath)
+        }
+
+        const impParts = path.normalize(impPath).split(path.sep)
+        const impFeaturesIdx = impParts.lastIndexOf(features)
+        if (impFeaturesIdx === -1) return
+
+        const targetFeature = impParts[impFeaturesIdx + 1]
+        if (!targetFeature) return
+
+        // skip reporting for ignored target features
+        if (isFileIgnored(targetFeature, ignore)) return
+
+        if (targetFeature !== sourceFeature) {
+          context.report({ node, messageId: 'forbidden', data: { targetFeature } })
+        }
+      },
+    }
+  },
+}
diff --git a/tests/rules/components-index-required.spec.js b/tests/rules/components-index-required.spec.js
@@ -0,0 +1,54 @@
+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('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('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()
+  })
+})
diff --git a/tests/rules/no-direct-feature-imports.test.js b/tests/rules/no-direct-feature-imports.test.js
@@ -0,0 +1,94 @@
+import path from 'path'
+import { describe, it, expect, beforeEach } from 'vitest'
+import { setupTest, runRule } from '../utils.js'
+import rule from '../../src/rules/no-direct-feature-imports.js'
+
+describe('vue-modular/no-direct-feature-imports', () => {
+  beforeEach(setupTest)
+
+  it('reports when importing directly from another feature', () => {
+    const filename = path.join(process.cwd(), 'src', 'features', 'auth', 'components', 'Button.vue')
+    const imports = [path.join(process.cwd(), 'src', 'features', 'payments', 'utils', 'api.js')]
+    const ctx = runRule(rule, filename, [{ features: 'features' }], imports)
+    expect(ctx.report).toHaveBeenCalled()
+  })
+
+  it('does not report when importing from shared', () => {
+    const filename = path.join(process.cwd(), 'src', 'features', 'auth', 'components', 'Button.vue')
+    const imports = [path.join(process.cwd(), 'src', 'shared', 'utils', 'api.js')]
+    const ctx = runRule(rule, filename, [{ features: 'features' }], imports)
+    expect(ctx.report).not.toHaveBeenCalled()
+  })
+
+  it('does not report when importing from same feature deep when allowed', () => {
+    const filename = path.join(process.cwd(), 'src', 'features', 'auth', 'components', 'Button.vue')
+    const imports = [path.join(process.cwd(), 'src', 'features', 'auth', 'utils', 'helper.js')]
+    const ctx = runRule(rule, filename, [{ features: 'features' }], imports)
+    expect(ctx.report).not.toHaveBeenCalled()
+  })
+
+  it('ignores virtual filenames and test files', () => {
+    const ctx1 = runRule(rule, '<input>', [{ features: 'features', imports: ['src/features/other/x.js'] }])
+    expect(ctx1.report).not.toHaveBeenCalled()
+
+    const filename = path.join(process.cwd(), 'tests', 'features', 'auth', 'components', 'Button.test.js')
+    const ctx2 = runRule(rule, filename, [{ features: 'features' }], ['src/features/other/x.js'])
+    expect(ctx2.report).not.toHaveBeenCalled()
+  })
+
+  it('does nothing when no imports option is provided', () => {
+    const filename = path.join(process.cwd(), 'src', 'features', 'auth', 'components', 'Button.vue')
+    const ctx = runRule(rule, filename, [{ features: 'features' }], undefined)
+    expect(ctx.report).not.toHaveBeenCalled()
+  })
+
+  it('ignores non-string imports', () => {
+    const filename = path.join(process.cwd(), 'src', 'features', 'auth', 'components', 'Button.vue')
+    const imports = [null, 123, {}]
+    const ctx = runRule(rule, filename, [{ features: 'features' }], imports)
+    expect(ctx.report).not.toHaveBeenCalled()
+  })
+
+  it('ignores imports that reference features segment only (no target feature)', () => {
+    const filename = path.join(process.cwd(), 'src', 'features', 'auth', 'components', 'Button.vue')
+    const imports = [path.join(process.cwd(), 'src', 'features')]
+    const ctx = runRule(rule, filename, [{ features: 'features' }], imports)
+    expect(ctx.report).not.toHaveBeenCalled()
+  })
+
+  it('does nothing when filename ends with the configured features segment (no source feature)', () => {
+    const filename = path.join(process.cwd(), 'src', 'features')
+    const imports = [path.join(process.cwd(), 'src', 'features', 'payments', 'utils', 'api.js')]
+    const ctx = runRule(rule, filename, [{ features: 'features' }], imports)
+    expect(ctx.report).not.toHaveBeenCalled()
+  })
+
+  it('does nothing when configured features folder is not in filename path', () => {
+    const filename = path.join(process.cwd(), 'src', 'other', 'auth', 'components', 'Button.vue')
+    const imports = [path.join(process.cwd(), 'src', 'features', 'payments', 'utils', 'api.js')]
+    const ctx = runRule(rule, filename, [{ features: 'features' }], imports)
+    expect(ctx.report).not.toHaveBeenCalled()
+  })
+
+  it('respects ignore option for target features', () => {
+    const filename = path.join(process.cwd(), 'src', 'features', 'auth', 'components', 'Button.vue')
+    const imports = [path.join(process.cwd(), 'src', 'features', 'payments', 'utils', 'api.js')]
+    const ctx = runRule(rule, filename, [{ features: 'features', ignore: ['payments'] }], imports)
+    expect(ctx.report).not.toHaveBeenCalled()
+  })
+
+  it('reports when a relative import resolves to another feature', () => {
+    const filename = path.join(process.cwd(), 'src', 'features', 'auth', 'components', 'Button.vue')
+    // from .../features/auth/components, ../../payments/... resolves to .../features/payments/...
+    const imports = ['../../payments/utils/api.js']
+    const ctx = runRule(rule, filename, [{ features: 'features' }], imports)
+    expect(ctx.report).toHaveBeenCalled()
+  })
+
+  it('resolves relative imports and respects ignore option', () => {
+    const filename = path.join(process.cwd(), 'src', 'features', 'auth', 'components', 'Button.vue')
+    const imports = ['../../payments/utils/api.js']
+    const ctx = runRule(rule, filename, [{ features: 'features', ignore: ['payments'] }], imports)
+    expect(ctx.report).not.toHaveBeenCalled()
+  })
+})
diff --git a/tests/utils.js b/tests/utils.js
@@ -25,14 +25,25 @@ export const setupTest = () => {
 }
 
 // Run a rule with the given context
-export const runRule = (rule, filename = 'index.js', options = [{}]) => {
+export const runRule = (rule, filename = 'index.js', options = [{}], imports = []) => {
+  const opts = Array.isArray(options) ? options : [options || {}]
   const context = {
-    options,
+    options: opts,
     getFilename: () => filename,
     report: vi.fn(),
     settings: {},
   }
   const ruleInstance = rule.create(context)
   if (ruleInstance.Program) ruleInstance.Program()
+
+  // If tests provided an `imports` array, synthesize minimal ImportDeclaration nodes
+  const importsArr = Array.isArray(imports) ? imports : []
+  if (Array.isArray(importsArr) && ruleInstance.ImportDeclaration) {
+    for (const imp of importsArr) {
+      // create a minimal node similar to ESTree ImportDeclaration
+      const node = { source: { value: imp } }
+      ruleInstance.ImportDeclaration(node)
+    }
+  }
   return context
 }

Original file line number	Diff line number	Diff line change
`@@ -5,6 +5,7 @@ const recommendedRules = {`
`5`	`5`	`'vue-modular/feature-index-required': 'error',`
`6`	`6`	`'vue-modular/components-index-required': 'error',`
`7`	`7`	`'vue-modular/shared-ui-index-required': 'error',`
	`8`	`+ 'vue-modular/no-direct-feature-imports': 'error',`
`8`	`9`	`}`
`9`	`10`
`10`	`11`	`const allRules = {`