Feat/sub barrel files

[alilaa]

Summary

This is a suggested implementation to resolve Support multiple entry files for a single module

Adds opt-in support for sub-barrel files — additional module entry points that follow the naming convention <barrelBaseName>.<suffix>.<ext>.

For example, with barrelFileName: 'public-api.ts', files like public-api.routing.ts and public-api.bookmarks.ts are recognized as valid imports without triggering encapsulation violations.

Motivation

Projects using a barrel file sometimes need to split their public API into logically grouped subsets (routing, bookmarks, models, etc.) to avoid issues with treeshaking . This feature enables that pattern while keeping module boundaries intact.

Changes

Configuration

• New optional config enableSubBarrelFileSupport: boolean (default false) — zero impact on existing users
• Added to UserSheriffConfig, Configuration, and defaultConfig

Core logic

• Module.isBarrelFile(filePath) — new method using pure string operations (no filesystem or path API calls) to check if a file is the main barrel or a sub-barrel. Computes barrelPrefix and barrelExt once in the constructor.
• accessesBarrelFileForBarrelModules — delegates to module.isBarrelFile() when the feature is enabled; falls back to the existing strict barrelPath === check otherwise.

ESLint error messages

• Removed the hardcoded (index.ts) reference from the deep-import error message, since users can configure a custom barrelFileName — the old message would be confusing when the barrel file is e.g. public-api.ts
• When enableSubBarrelFileSupport is enabled, the message now suggests using "the module's barrel file or a sub-barrel file"
• When disabled, the message says "the module's barrel file" (without mentioning index.ts)

Documentation

• configuration.md: documented enableSubBarrelFileSupport option and updated barrelFileName description
• module_boundaries.md: new "Sub-Barrel Files" section

Tests

• 16 unit tests for Module.isBarrelFile() covering: main barrel, sub-barrel with default/custom barrel names, non-barrel files, files in subdirectories, partial prefix matches, and edge cases
• 8 integration tests for encapsulation violations with sub-barrel imports (enabled/disabled, barrel/barrel-less modules)
• Updated existing test-project fixtures for the updated error message wording

Commits

1. feat(core): support sub-barrel files in encapsulation checks — config + Module.isBarrelFile + encapsulation check + ESLint message
2. test(core): add tests for sub-barrel file support — unit and integration tests
3. test(test-projects): update encapsulation fixtures for new error message — fixture updates for wording change
4. docs(docs): document sub-barrel files and enableSubBarrelFileSupport — documentation

Notes

• Feature is behind enableSubBarrelFileSupport: false by default — no behavioral change for existing users
• If enabled without barrel files (barrel-less modules), the feature is safely ignored
• Zero new dependencies — uses only string operations
• Sub-barrel files act only as additional entry points; module boundaries are still defined by the main barrel file

[sonarqubecloud]

Quality Gate passed

Issues
2 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud