eslint-plugin-barrel-rules 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 RakHyeon-Sung
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.ko.md

@@ -0,0 +1,123 @@
+# 🛡️ eslint-plugin-barrel-rules
+
+# **Advanced Barrel Pattern Enforcement for JavaScript/TypeScript Projects**
+
+<div align="center">
+  <img src="https://img.shields.io/badge/version-1.0.0-blue.svg" alt="Version"/>
+  <img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License"/>
+  <img src="https://img.shields.io/badge/PRs-welcome-brightgreen.svg" alt="PRs Welcome"/>
+</div>
+
+<div align="center">
+  <img width="320" alt="Scry" src="https://github.com/user-attachments/assets/dc11d2d4-3896-4def-bf5f-e778086a3de8" />
+</div>
+
+Github: [https://github.com/racgoo/eslint-plugin-barrel-module](https://github.com/racgoo/eslint-plugin-barrel-module)
+
+NPM: [https://github.com/racgoo/eslint-plugin-barrel-module](https://github.com/racgoo/eslint-plugin-barrel-module)
+
+---
+
+## 소개
+
+**eslint-plugin-barrel-rules**는  
+JavaScript/TypeScript 프로젝트에서 Barrel Pattern(배럴 패턴)을 강제하고, 모듈 경계와 캡슐화를 보장하는 고급 ESLint 플러그인입니다.
+
+지정한 디렉토리(예: `src/domains/*`)의 내부 구현은  
+오직 해당 디렉토리의 **index(배럴) 파일**을 통해서만 접근할 수 있도록 강제합니다.  
+내부 파일을 직접 import하는 것을 차단하여  
+**모듈화, 추상화, 유지보수성, 확장성**을 극대화합니다.
+
+---
+
+## 지원 환경
+
+- Node.js (ES2015+)
+- ES Modules(ESM)
+
+---
+
+## 주요 기능
+
+- **Barrel Pattern 강제**  
+  지정한 디렉토리의 index(배럴) 파일을 통해서만 import를 허용  
+  (예: `import ... from "../domains/foo"`는 허용,  
+  `import ... from "../domains/foo/components/Bar"`는 차단)
+
+- **고성능 glob 매칭**  
+  `src/domains/*`처럼 glob 패턴으로 여러 디렉토리 지정 가능
+
+---
+
+## 설치
+
+```bash
+npm i eslint-plugin-barrel-rules --save-dev
+# or
+yarn add -D eslint-plugin-barrel-rules
+# or
+pnpm add -D eslint-plugin-barrel-rules
+```
+
+---
+
+## 사용법
+
+```js
+import { fileURLToPath } from "url";
+import path from "path";
+import { enforceBarrelPattern } from "eslint-plugin-barrel-rules";
+
+//ESM은 __dirname을 지원하지 않기에 직접 구현합니다.
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+export default [
+  {
+    plugins: {
+      "barrel-rules": enforceBarrelPattern,
+    },
+    rules: {
+      "barrel-rules/enforce-barrel-pattern": [
+        "error",
+        {
+          //Barrel Pattern을 강제할 디렉토리를 정의합니다(baseDir 기준으로 상대경로)
+          paths: ["src/domains/*"],
+          //paths들의 root경로를 지정합니다.
+          baseDir: __dirname,
+        },
+      ],
+    },
+  },
+];
+```
+
+---
+
+## 예시
+
+```ts
+// ❌ 내부 파일을 직접 import하면 차단됩니다.
+import { Test } from "../domains/foo/components/Test";
+
+// ✅ 반드시 배럴(index) 파일을 통해 import해야 합니다.
+import { Test } from "../domains/foo";
+```
+
+---
+
+## 앞으로의 계획
+
+- 더 다양한 모듈 경계/추상화 관련 룰 추가 예정
+
+- **Alias/tsconfig 지원**  
+  TypeScript `paths`, Vite `resolve.alias` 등 다양한 경로 매핑 완벽 지원 예정
+
+- **Commonjs 지원**
+
+---
+
+## 문의
+
+질문, 제안, 버그 리포트, 기여 모두 환영합니다!  
+[[📬 send mail]](mailto:lhsung98@naver.com)

package/README.md

@@ -0,0 +1,126 @@
+# 🛡️ eslint-plugin-barrel-rules
+
+# **Advanced Barrel Pattern Enforcement for JavaScript/TypeScript Projects**
+
+<div align="center">
+  <img src="https://img.shields.io/badge/version-1.0.0-blue.svg" alt="Version"/>
+  <img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License"/>
+  <img src="https://img.shields.io/badge/PRs-welcome-brightgreen.svg" alt="PRs Welcome"/>
+</div>
+
+<div align="center">
+  <img width="320" alt="Scry" src="https://github.com/user-attachments/assets/dc11d2d4-3896-4def-bf5f-e778086a3de8" />
+</div>
+
+Github: [https://github.com/racgoo/eslint-plugin-barrel-module](https://github.com/racgoo/eslint-plugin-barrel-module)
+
+NPM: [https://github.com/racgoo/eslint-plugin-barrel-module](https://github.com/racgoo/eslint-plugin-barrel-module)
+
+🇰🇷 [README (Korean)](./README.ko.md)
+
+---
+
+## Introduction
+
+**eslint-plugin-barrel-rules** is an advanced ESLint plugin  
+that enforces the Barrel Pattern in JavaScript/TypeScript projects,  
+ensuring strict module boundaries and encapsulation.
+
+You can specify directories (e.g., `src/domains/*`) where  
+internal implementation details must only be accessed via the directory’s **index (barrel) file**.  
+Direct imports from internal files are blocked, maximizing  
+**modularity, abstraction, maintainability, and scalability**.
+
+---
+
+## Supports
+
+- Node.js (ES2015+)
+- Supports ES Modules (ESM)
+
+---
+
+## Features
+
+- **Barrel Pattern Enforcement**  
+  Only allows imports from the index (barrel) file of specified directories  
+  (e.g., `import ... from "../domains/foo"` is allowed,  
+  but `import ... from "../domains/foo/components/Bar"` is blocked)
+
+- **High-performance glob matching**  
+  Specify multiple directories using glob patterns like `src/domains/*`
+
+---
+
+## Install
+
+```bash
+npm i eslint-plugin-barrel-rules --save-dev
+# or
+yarn add -D eslint-plugin-barrel-rules
+# or
+pnpm add -D eslint-plugin-barrel-rules
+```
+
+---
+
+## Usage
+
+```js
+import { fileURLToPath } from "url";
+import path from "path";
+import { enforceBarrelPattern } from "eslint-plugin-barrel-rules";
+
+//ESM not support __dirname(custom __dirname)
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+export default [
+  {
+    plugins: {
+      "barrel-rules": enforceBarrelPattern,
+    },
+    rules: {
+      "barrel-rules/enforce-barrel-pattern": [
+        "error",
+        {
+          //Enforced directories
+          paths: ["src/domains/*"],
+          //BaseDir(root path, mutable)
+          baseDir: __dirname,
+        },
+      ],
+    },
+  },
+];
+```
+
+---
+
+## Example
+
+```ts
+// ❌ Direct import from internal file is blocked
+import { Test } from "../domains/foo/components/Test";
+
+// ✅ Must import via the barrel (index) file
+import { Test } from "../domains/foo";
+```
+
+---
+
+## Future Work
+
+- More rules for module boundaries and abstraction
+
+- **Alias/tsconfig Support**  
+  Fully supports TypeScript `paths`, Vite `resolve.alias`, and other custom path mappings
+
+- **CJS Support**
+
+---
+
+## Contact
+
+Questions, suggestions, bug reports, and contributions are welcome!  
+[[📬 send mail]](mailto:lhsung98@naver.com)

package/dist/index.cjs

@@ -0,0 +1,131 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  enforceBarrelPattern: () => enforceBarrelPattern
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/rules/enforce-barrel-pattern.ts
+var import_utils = require("@typescript-eslint/utils");
+var import_path = __toESM(require("path"), 1);
+var import_resolve = __toESM(require("resolve"), 1);
+var import_fast_glob = __toESM(require("fast-glob"), 1);
+var enforceBarrelPattern = {
+  meta: {
+    type: "problem",
+    docs: {
+      description: "Only barrel pattern imports are allowed in this module."
+    },
+    schema: [
+      {
+        type: "object",
+        properties: {
+          paths: { type: "array", items: { type: "string" } },
+          baseDir: { type: "string" }
+        },
+        additionalProperties: false
+      }
+    ],
+    messages: {
+      DirectImportDisallowed: "Please import from '{{matchedTargetPath}}'. Direct access to '{{rawImportPath}}' is not allowed. You must use the barrel pattern and only consume APIs exposed externally. This is to ensure encapsulation of internal logic and maintain module boundaries."
+    }
+  },
+  //default options(baseDir is current working directory. almost user execute eslint in project root)
+  defaultOptions: [{ paths: [], baseDir: process.cwd() }],
+  create(context) {
+    const options = context.options[0];
+    const baseDir = options.baseDir;
+    const targetPaths = options.paths.flatMap(
+      (_path) => import_fast_glob.default.sync(_path, {
+        cwd: baseDir,
+        onlyDirectories: true,
+        absolute: true
+      })
+    );
+    return {
+      //check only import declaration(ESM)
+      ImportDeclaration(node) {
+        const rawImportPath = node.source.value;
+        const absoluteCurrentFilePath = context.getFilename();
+        let absoluteImportPath = null;
+        try {
+          absoluteImportPath = import_resolve.default.sync(rawImportPath, {
+            basedir: import_path.default.dirname(absoluteCurrentFilePath),
+            extensions: [
+              ".ts",
+              ".tsx",
+              ".js",
+              ".jsx",
+              ".json",
+              ".d.ts",
+              ".mjs",
+              ".cjs"
+            ]
+          });
+        } catch (e) {
+          return;
+        }
+        let matchedLatestTargetPath = null;
+        const invalidDirectedImport = targetPaths.some((targetPath) => {
+          const targetPathEntryPoints = [
+            "index.ts",
+            "index.tsx",
+            "index.js",
+            "index.jsx",
+            "index.cjs",
+            "index.mjs",
+            "index.d.ts"
+          ].map((entry) => import_path.default.resolve(targetPath, entry));
+          const closedTargetPath = targetPath + "/";
+          const targetPathEntryPointed = targetPathEntryPoints.includes(absoluteImportPath);
+          const importedOutsideOfTargetPath = !absoluteCurrentFilePath.startsWith(closedTargetPath) && absoluteImportPath.startsWith(closedTargetPath);
+          const invalidImported = !targetPathEntryPointed && importedOutsideOfTargetPath;
+          if (invalidImported) {
+            matchedLatestTargetPath = targetPath;
+          }
+          return invalidImported;
+        });
+        if (invalidDirectedImport) {
+          context.report({
+            node,
+            messageId: "DirectImportDisallowed",
+            data: { rawImportPath, matchedTargetPath: matchedLatestTargetPath }
+          });
+        }
+      }
+    };
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  enforceBarrelPattern
+});

package/dist/index.d.cts

@@ -0,0 +1,10 @@
+import { RuleModule } from '@typescript-eslint/utils/ts-eslint';
+
+type Options = [{
+    paths: string[];
+    baseDir: string;
+}];
+type MessageIds = "DirectImportDisallowed";
+declare const enforceBarrelPattern: RuleModule<MessageIds, Options>;
+
+export { enforceBarrelPattern };

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+import { RuleModule } from '@typescript-eslint/utils/ts-eslint';
+
+type Options = [{
+    paths: string[];
+    baseDir: string;
+}];
+type MessageIds = "DirectImportDisallowed";
+declare const enforceBarrelPattern: RuleModule<MessageIds, Options>;
+
+export { enforceBarrelPattern };

package/dist/index.js

@@ -0,0 +1,94 @@
+// src/rules/enforce-barrel-pattern.ts
+import "@typescript-eslint/utils";
+import path from "path";
+import resolve from "resolve";
+import fastGlob from "fast-glob";
+var enforceBarrelPattern = {
+  meta: {
+    type: "problem",
+    docs: {
+      description: "Only barrel pattern imports are allowed in this module."
+    },
+    schema: [
+      {
+        type: "object",
+        properties: {
+          paths: { type: "array", items: { type: "string" } },
+          baseDir: { type: "string" }
+        },
+        additionalProperties: false
+      }
+    ],
+    messages: {
+      DirectImportDisallowed: "Please import from '{{matchedTargetPath}}'. Direct access to '{{rawImportPath}}' is not allowed. You must use the barrel pattern and only consume APIs exposed externally. This is to ensure encapsulation of internal logic and maintain module boundaries."
+    }
+  },
+  //default options(baseDir is current working directory. almost user execute eslint in project root)
+  defaultOptions: [{ paths: [], baseDir: process.cwd() }],
+  create(context) {
+    const options = context.options[0];
+    const baseDir = options.baseDir;
+    const targetPaths = options.paths.flatMap(
+      (_path) => fastGlob.sync(_path, {
+        cwd: baseDir,
+        onlyDirectories: true,
+        absolute: true
+      })
+    );
+    return {
+      //check only import declaration(ESM)
+      ImportDeclaration(node) {
+        const rawImportPath = node.source.value;
+        const absoluteCurrentFilePath = context.getFilename();
+        let absoluteImportPath = null;
+        try {
+          absoluteImportPath = resolve.sync(rawImportPath, {
+            basedir: path.dirname(absoluteCurrentFilePath),
+            extensions: [
+              ".ts",
+              ".tsx",
+              ".js",
+              ".jsx",
+              ".json",
+              ".d.ts",
+              ".mjs",
+              ".cjs"
+            ]
+          });
+        } catch (e) {
+          return;
+        }
+        let matchedLatestTargetPath = null;
+        const invalidDirectedImport = targetPaths.some((targetPath) => {
+          const targetPathEntryPoints = [
+            "index.ts",
+            "index.tsx",
+            "index.js",
+            "index.jsx",
+            "index.cjs",
+            "index.mjs",
+            "index.d.ts"
+          ].map((entry) => path.resolve(targetPath, entry));
+          const closedTargetPath = targetPath + "/";
+          const targetPathEntryPointed = targetPathEntryPoints.includes(absoluteImportPath);
+          const importedOutsideOfTargetPath = !absoluteCurrentFilePath.startsWith(closedTargetPath) && absoluteImportPath.startsWith(closedTargetPath);
+          const invalidImported = !targetPathEntryPointed && importedOutsideOfTargetPath;
+          if (invalidImported) {
+            matchedLatestTargetPath = targetPath;
+          }
+          return invalidImported;
+        });
+        if (invalidDirectedImport) {
+          context.report({
+            node,
+            messageId: "DirectImportDisallowed",
+            data: { rawImportPath, matchedTargetPath: matchedLatestTargetPath }
+          });
+        }
+      }
+    };
+  }
+};
+export {
+  enforceBarrelPattern
+};

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "eslint-plugin-barrel-rules",
+  "description": "Enforce barrel module pattern",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/racgoo/eslint-plugin-barrel-module"
+  },
+  "bugs": {
+    "url": "https://github.com/racgoo/eslint-plugin-barrel-module/issues"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "license": "MIT",
+  "keywords": [
+    "eslint",
+    "eslint-plugin",
+    "eslint-plugin-barrel-rules",
+    "barrel-module",
+    "barrel pattern",
+    "encapsulation directory",
+    "enforce barrel pattern"
+  ],
+  "version": "1.0.0",
+  "type": "module",
+  "main": "dist/index.cjs",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "dependencies": {
+    "@typescript-eslint/utils": "^8.36.0",
+    "fast-glob": "^3.3.3",
+    "resolve": "^1.22.10",
+    "tsconfig-paths": "^4.2.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.13",
+    "@types/resolve": "^1.20.6",
+    "tsup": "^8.5.0",
+    "typescript": "~5.8.3"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --dts --format cjs,esm",
+    "type-check": "tsc --noEmit",
+    "release": "pnpm run build && pnpm publish --access=public"
+  }
+}