eslint-plugin-import-boundaries 0.1.0

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2025, ClassicalMoser
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -0,0 +1,299 @@
+# eslint-plugin-import-boundaries
+
+> Enforce architectural boundaries with deterministic import paths.
+
+[![npm version](https://img.shields.io/npm/v/eslint-plugin-import-boundaries)](https://www.npmjs.com/package/eslint-plugin-import-boundaries)
+[![License: ISC](https://img.shields.io/badge/License-ISC-blue.svg)](https://opensource.org/licenses/ISC)
+
+**Note: This is a beta release developed for a personal project. It is not yet stable and may have breaking changes.**
+
+An ESLint rule that enforces architectural boundaries using deterministic import path rules. This rule determines when to use alias vs relative imports based on your architecture, rather than enforcing a single pattern for all imports.
+
+## Features
+
+- **Deterministic**: One correct path for every import
+- **Explicit Exports**: Ensures every directory is explicit about what it exports (via barrel files)
+- **Readable Paths**: Resolves to logical, readable filepaths (no `../../../../../../` chains)
+- **Architectural Boundaries**: Enforce clean architecture, hexagonal architecture, or any non-nested boundary pattern (nested boundaries planned but not ready)
+- **Auto-fixable**: Most violations are automatically fixable
+- **Zero I/O**: Pure path math and AST analysis - fast even on large codebases
+- **Type-aware**: Different rules for type-only imports vs value imports
+- **Circular Dependency Prevention**: Blocks ancestor barrel imports
+- **Configurable**: Works with any architectural pattern
+
+## Quick Start
+
+```bash
+npm install --save-dev eslint-plugin-import-boundaries
+```
+
+```javascript
+// eslint.config.js
+import importBoundaries from 'eslint-plugin-import-boundaries';
+
+export default {
+  plugins: {
+    'import-boundaries': importBoundaries,
+  },
+  rules: {
+    'import-boundaries/enforce': [
+      'error',
+      {
+        rootDir: 'src',
+        boundaries: [
+          { dir: 'domain/entities', alias: '@entities' },
+          { dir: 'domain/queries', alias: '@queries' },
+          { dir: 'domain/events', alias: '@events' },
+        ],
+      },
+    ],
+  },
+};
+```
+
+## What Problem Does This Solve?
+
+Most projects have inconsistent import patterns:
+
+- Sometimes `@entities`, sometimes `../entities`, sometimes `../../domain/entities`
+- No clear rules for when to use alias vs relative
+- Import formatting discussions waste time in code reviews
+- Long relative paths like `../../../../../../utils` are hard to read
+- Absolute paths might not fit your architecture (`src/domain/entities/army/unit/weapon/sword`)
+- Directories aren't explicit about their exports (no barrel files)
+- Architectural boundaries are violated without enforcement
+- Circular dependencies sneak in
+- Refactoring is risky because import paths are ambiguous
+
+This rule provides deterministic import paths with architectural boundary enforcement - one correct answer for every import, eliminating debates and making refactoring safer.
+
+## Core Rules
+
+### 1. Cross-Boundary Imports → Alias
+
+When importing from a different boundary, always use the boundary alias (no subpaths):
+
+```typescript
+// ✅ CORRECT
+import { Entity } from '@entities';
+import { Query } from '@queries';
+
+// ❌ WRONG
+import { Entity } from '@entities/army'; // Subpath not allowed
+import { Entity } from '../entities'; // Relative not allowed
+```
+
+### 2. Same-Boundary Imports → Relative (when close)
+
+When importing within the same boundary, use relative paths for close imports:
+
+```typescript
+// Same directory (sibling)
+import { helper } from './helper'; // ✅
+
+// Parent's sibling (cousin, max one ../)
+import { utils } from '../utils'; // ✅
+
+// Top-level or distant → Use alias
+import { something } from '@queries/topLevel'; // ✅
+```
+
+### 3. Architectural Boundary Enforcement
+
+Prevent violations of your architecture:
+
+```javascript
+{
+  dir: 'domain/entities',
+  alias: '@entities',
+  allowImportsFrom: ['@events'],  // Only allow imports from @events
+  denyImportsFrom: ['@queries'],  // Deny imports from @queries
+}
+```
+
+```typescript
+// ✅ ALLOWED: @entities can import from @events
+import { Event } from '@events';
+
+// ❌ VIOLATION: @entities cannot import from @queries
+import { Query } from '@queries';
+// Error: Cannot import from '@queries' to '@entities': Import not allowed
+```
+
+### 4. Type-Only Imports
+
+Different rules for types vs values (types don't create runtime dependencies):
+
+```javascript
+{
+  dir: 'domain/entities',
+  alias: '@entities',
+  allowImportsFrom: ['@events'],           // Value imports
+  allowTypeImportsFrom: ['@events', '@queries'], // Type imports (more permissive)
+}
+```
+
+```typescript
+// ✅ ALLOWED: Type import from @queries
+import type { QueryResult } from '@queries';
+
+// ❌ VIOLATION: Value import from @queries
+import { executeQuery } from '@queries';
+```
+
+### 5. Ancestor Barrel Prevention
+
+Prevents circular dependencies by blocking ancestor barrel imports:
+
+```typescript
+// ❌ FORBIDDEN: Would create circular dependency
+import { something } from '@queries'; // When inside @queries boundary
+// Error: Cannot import from ancestor barrel '@queries'.
+//        This would create a circular dependency.
+```
+
+## Configuration
+
+### Basic Configuration
+
+```javascript
+{
+  rootDir: 'src',                    // Root directory (default: 'src')
+  crossBoundaryStyle: 'alias',      // 'alias' | 'absolute' (default: 'alias')
+  defaultSeverity: 'error',         // 'error' | 'warn' (default: 'error')
+  allowUnknownBoundaries: false,    // Allow imports outside boundaries (default: false)
+  skipBoundaryRulesForTestFiles: true, // Skip boundary rules for tests (default: true)
+  boundaries: [                    // Required: Array of boundary definitions
+    {
+      dir: 'domain/entities',       // Required: Relative directory path
+      alias: '@entities',           // Required: Import alias
+      severity: 'error',            // Optional: Override default severity
+      allowImportsFrom: ['@events'], // Optional: Allowed boundaries (value imports)
+      denyImportsFrom: ['@queries'], // Optional: Denied boundaries
+      allowTypeImportsFrom: ['@events', '@queries'], // Optional: Allowed for types
+    },
+  ],
+}
+```
+
+### Test Files Configuration
+
+Use ESLint's file matching for test files:
+
+```javascript
+export default [
+  {
+    files: ['src/**/*.ts'],
+    rules: {
+      'import-boundaries/enforce': [
+        'error',
+        {
+          /* config */
+        },
+      ],
+    },
+  },
+  {
+    files: ['**/*.test.{ts,js}', '**/*.spec.{ts,js}'],
+    rules: {
+      'import-boundaries/enforce': [
+        'error',
+        {
+          skipBoundaryRulesForTestFiles: true, // Tests can import from any boundary
+          // ... rest of config
+        },
+      ],
+    },
+  },
+];
+```
+
+## How It Works
+
+The rule uses pure path math - no file I/O, just deterministic algorithms:
+
+1. **Boundary Detection**: Determines which boundary a file belongs to
+2. **Path Calculation**: Calculates the correct import path using the "first differing segment" algorithm
+3. **Boundary Rules**: Checks allow/deny rules for cross-boundary imports
+4. **Type Detection**: Distinguishes type-only imports from value imports
+
+### Barrel Files as Module Interface
+
+The rule assumes barrel files (`index.ts`) are the module interface for each directory. This means:
+
+- `./dir` imports from `dir/index.ts` (the barrel)
+- You cannot bypass the barrel: `./dir/file` is not allowed
+- This enforces a clear public API for each module
+
+This barrel file assumption enables zero I/O: because we know every directory has a barrel file, we can determine correct paths using pure path math - no file system access needed. This makes the rule fast, reliable, and deterministic.
+
+The rule is barrel-agnostic - it enforces the path pattern (must go through the barrel), not what the barrel exports. Whether you use selective exports (`export { A, B } from './module'`) or universal exports (`export * from './module'`) is your choice based on your codebase needs.
+
+**Scale considerations**:
+
+- **Small projects**: If you have boundaries worth enforcing, you have enough structure for barrel files. For truly tiny projects (single file), this rule may be overkill.
+- **Large projects**: The pattern works at any scale. Performance depends on what you export (use selective exports in large apps), not the pattern itself. The rule's zero I/O approach means it stays fast even in massive codebases.
+- **Monorepos**: Works across packages, but requires manual configuration. You'd configure boundaries that span packages (e.g., `{ dir: 'packages/pkg-a/src/domain', alias: '@pkg-a/domain' }`). Each package maintains its own barrel structure, and the rule enforces boundaries between them based on your configuration.
+
+## What Gets Skipped
+
+The rule automatically skips checking for:
+
+- External packages (`node_modules`, npm packages)
+- Imports that don't match any boundary alias and aren't relative paths
+
+Only internal imports (relative paths, boundary aliases, and absolute paths within `rootDir`) are checked.
+
+## Error Messages
+
+Clear, actionable error messages:
+
+```
+Expected '@entities' but got '@entities/army'
+Expected './sibling' but got '@queries/sibling'
+Expected '../cousin' but got '@queries/nested/cousin'
+Cannot import from '@queries' to '@entities': Import not allowed
+Cannot import from ancestor barrel '@queries'. This would create a circular dependency.
+```
+
+## Comparison with Other Plugins
+
+### Simple Path Enforcers
+
+Plugins like `eslint-plugin-no-relative-import-paths` and `eslint-plugin-absolute-imports` only enforce "use absolute paths everywhere" or "use relative paths everywhere." They don't handle:
+
+- Deterministic alias vs relative (when to use which)
+- Architectural boundaries
+- Allow/deny rules between boundaries
+- Type-only import handling
+- Circular dependency prevention
+- Barrel file enforcement
+
+### Architectural Boundary Plugins
+
+`eslint-plugin-boundaries` does enforce architectural boundaries, but uses a different approach:
+
+- Pattern-based element matching (more complex configuration)
+- File I/O for resolution (slower, requires file system access)
+- Different rule structure
+
+This plugin uses a different approach:
+
+- Simple, deterministic path rules (pure path math, zero I/O)
+- Architectural boundary enforcement
+- Type-aware rules
+- Fast and auto-fixable
+
+By assuming barrel files at every directory, this plugin can determine correct paths using pure path math - no file system access needed. This makes it faster and more reliable. The barrel file pattern also enforces clear module interfaces (you must go through the barrel), which is good architecture. Because paths are deterministic, there's no debugging overhead - you always know exactly where a module comes from.
+
+## Roadmap
+
+- **Nested Boundaries**: Support for nested boundaries where sub-boundaries can have broader allow patterns than their parents (e.g., `@ports` nested in `@application` can import from `@infrastructure` even though `@application` cannot). This is required for proper hexagonal architecture support. See [Nested Boundaries Design](./NESTED_BOUNDARIES_DESIGN.md) for the design document.
+
+## License
+
+ISC
+
+## Contributing
+
+Contributions welcome! Please open an issue or PR.

package/eslint-plugin-import-boundaries.js

@@ -0,0 +1,462 @@
+import path from "node:path";
+import process from "node:process";
+
+//#region eslint-plugin-import-boundaries/pathUtils.ts
+/**
+* Path utility functions for the boundary-alias-vs-relative ESLint rule.
+* Pure path math - no file I/O.
+*/
+/**
+* Check if a path is inside a directory.
+* Uses path.relative() which is more reliable than string comparison.
+*
+* @param absDir - Absolute directory path
+* @param absPath - Absolute file or directory path to check
+* @returns true if absPath is inside absDir (or is absDir itself)
+*
+* Examples:
+* - isInsideDir('/a/b', '/a/b/file.ts') => true
+* - isInsideDir('/a/b', '/a/b/c/file.ts') => true
+* - isInsideDir('/a/b', '/a/file.ts') => false (../file.ts)
+* - isInsideDir('/a/b', '/a/b') => true (empty relative path)
+*/
+function isInsideDir(absDir, absPath) {
+	const rel = path.relative(absDir, absPath);
+	if (rel === "") return true;
+	return !rel.startsWith("..") && !path.isAbsolute(rel);
+}
+
+//#endregion
+//#region eslint-plugin-import-boundaries/boundaryDetection.ts
+/**
+* Check if an import specifier is using an alias subpath (e.g., '@entities/army').
+* Subpaths should be converted to the base alias (e.g., '@entities').
+*
+* @param spec - Import specifier to check
+* @param boundaries - Array of resolved boundaries
+* @returns Object indicating if it's a subpath and which base alias it uses
+*
+* Examples:
+* - checkAliasSubpath('@entities/army', boundaries) => { isSubpath: true, baseAlias: '@entities' }
+* - checkAliasSubpath('@entities', boundaries) => { isSubpath: false }
+*/
+function checkAliasSubpath(spec, boundaries) {
+	for (const b of boundaries) if (spec.startsWith(`${b.alias}/`)) return {
+		isSubpath: true,
+		baseAlias: b.alias
+	};
+	return { isSubpath: false };
+}
+/**
+* Get metadata about the current file being linted.
+* Results are cached per file to avoid recomputation.
+*
+* @param filename - Absolute filename from ESLint context
+* @param boundaries - Array of resolved boundaries
+* @returns FileData with directory and boundary information, or { isValid: false } if file path is invalid
+*/
+function getFileData(filename, boundaries) {
+	if (!path.isAbsolute(filename)) return { isValid: false };
+	const fileDir = path.dirname(filename);
+	const matchingBoundaries = boundaries.filter((b) => isInsideDir(b.absDir, filename));
+	return {
+		isValid: true,
+		fileDir,
+		fileBoundary: matchingBoundaries.length > 0 ? matchingBoundaries.sort((a, b) => b.absDir.length - a.absDir.length)[0] : null
+	};
+}
+
+//#endregion
+//#region eslint-plugin-import-boundaries/boundaryRules.ts
+/**
+* Check if an import from fileBoundary to targetBoundary is allowed.
+* Returns violation info if not allowed, null if allowed.
+*
+* Semantics:
+* - If both allowImportsFrom and denyImportsFrom are specified, they work as:
+*   - allowImportsFrom: explicit allow list (overrides deny for those items)
+*   - denyImportsFrom: explicit deny list (overrides default allow for those items)
+* - If only allowImportsFrom: only those boundaries are allowed (deny-all by default)
+* - If only denyImportsFrom: all boundaries allowed except those (allow-all by default)
+* - If neither: deny-all by default (strictest)
+* - allowTypeImportsFrom: For type-only imports, this overrides allowImportsFrom (allows types from more boundaries)
+*/
+function checkBoundaryRules(fileBoundary, targetBoundary, allBoundaries, isTypeOnly = false) {
+	if (fileBoundary === targetBoundary) return null;
+	if (isTypeOnly && fileBoundary.allowTypeImportsFrom?.includes(targetBoundary.alias)) return null;
+	const hasAllowList = fileBoundary.allowImportsFrom && fileBoundary.allowImportsFrom.length > 0;
+	const hasDenyList = fileBoundary.denyImportsFrom && fileBoundary.denyImportsFrom.length > 0;
+	if (hasAllowList && fileBoundary.allowImportsFrom.includes(targetBoundary.alias)) return null;
+	if (hasDenyList && fileBoundary.denyImportsFrom.includes(targetBoundary.alias)) return { reason: `Boundary '${fileBoundary.alias}' explicitly denies imports from '${targetBoundary.alias}'` };
+	if (hasAllowList && !hasDenyList) return { reason: `Cross-boundary import from '${targetBoundary.alias}' to '${fileBoundary.alias}' is not allowed. Add '${targetBoundary.alias}' to 'allowImportsFrom' if this import is intentional.` };
+	if (hasDenyList && !hasAllowList) return null;
+	return { reason: `Cross-boundary import from '${targetBoundary.alias}' to '${fileBoundary.alias}' is not allowed. Add '${targetBoundary.alias}' to 'allowImportsFrom' if this import is intentional.` };
+}
+
+//#endregion
+//#region eslint-plugin-import-boundaries/fixer.ts
+/**
+* Create a fixer function to replace an import path.
+* Handles different import node types: ImportDeclaration, ImportExpression, require().
+*
+* @param node - AST node for the import
+* @param newPath - New import path to use
+* @returns Fixer function, or null if node type is unsupported
+*/
+function createFixer(node, newPath) {
+	return (fixer) => {
+		if ("source" in node && node.source) return fixer.replaceText(node.source, `'${newPath}'`);
+		if ("arguments" in node && Array.isArray(node.arguments) && node.arguments[0]) return fixer.replaceText(node.arguments[0], `'${newPath}'`);
+		return null;
+	};
+}
+
+//#endregion
+//#region eslint-plugin-import-boundaries/relationshipDetection.ts
+/**
+* Resolve the target path from an import specifier.
+*/
+function resolveTargetPath(rawSpec, fileDir, boundaries, rootDir, cwd) {
+	let targetAbs;
+	let targetDir;
+	if (rawSpec.startsWith("@")) {
+		const boundary = boundaries.find((b) => rawSpec === b.alias || rawSpec.startsWith(`${b.alias}/`));
+		if (boundary) {
+			const subpath = rawSpec.slice(boundary.alias.length + 1);
+			if (subpath && !subpath.endsWith(".ts")) {
+				targetDir = path.resolve(boundary.absDir, subpath);
+				targetAbs = path.join(targetDir, "index.ts");
+			} else if (subpath) {
+				targetAbs = path.resolve(boundary.absDir, subpath);
+				targetDir = path.dirname(targetAbs);
+			} else {
+				targetAbs = path.join(boundary.absDir, "index.ts");
+				targetDir = boundary.absDir;
+			}
+		} else {
+			targetAbs = "";
+			targetDir = "";
+		}
+	} else if (rawSpec.startsWith(".")) if (!rawSpec.endsWith(".ts")) {
+		targetDir = path.resolve(fileDir, rawSpec);
+		targetAbs = path.join(targetDir, "index.ts");
+	} else {
+		targetAbs = path.resolve(fileDir, rawSpec);
+		targetDir = path.dirname(targetAbs);
+	}
+	else if (rawSpec.startsWith(rootDir)) if (!rawSpec.endsWith(".ts")) {
+		targetDir = path.resolve(cwd, rawSpec);
+		targetAbs = path.join(targetDir, "index.ts");
+	} else {
+		targetAbs = path.resolve(cwd, rawSpec);
+		targetDir = path.dirname(targetAbs);
+	}
+	else {
+		targetAbs = "";
+		targetDir = "";
+	}
+	return {
+		targetAbs,
+		targetDir
+	};
+}
+/**
+* Calculate the correct import path using the simplified algorithm.
+*/
+function calculateCorrectImportPath(rawSpec, fileDir, fileBoundary, boundaries, rootDir, cwd, crossBoundaryStyle = "alias") {
+	const { targetAbs, targetDir } = resolveTargetPath(rawSpec, fileDir, boundaries, rootDir, cwd);
+	const targetBoundary = boundaries.find((b) => isInsideDir(b.absDir, targetAbs)) ?? null;
+	if (!fileBoundary || targetBoundary !== fileBoundary) {
+		if (targetBoundary) {
+			if (crossBoundaryStyle === "absolute") return path.join(rootDir, targetBoundary.dir).replace(/\\/g, "/");
+			return targetBoundary.alias;
+		}
+		return "UNKNOWN_BOUNDARY";
+	}
+	if (rawSpec === fileBoundary.alias) return null;
+	const targetRelativeToBoundary = path.relative(fileBoundary.absDir, targetDir);
+	const fileRelativeToBoundary = path.relative(fileBoundary.absDir, fileDir);
+	const targetParts = targetRelativeToBoundary === "" || targetRelativeToBoundary === "." ? [] : targetRelativeToBoundary.split(path.sep).filter((p) => p && p !== ".");
+	const fileParts = fileRelativeToBoundary === "" || fileRelativeToBoundary === "." ? [] : fileRelativeToBoundary.split(path.sep).filter((p) => p && p !== ".");
+	if (targetParts.length === 0) {
+		const targetBasename = path.basename(targetAbs, ".ts");
+		if (targetBasename !== "index") return `${fileBoundary.alias}/${targetBasename}`;
+		return null;
+	}
+	let firstDifferingIndex = 0;
+	while (firstDifferingIndex < targetParts.length && firstDifferingIndex < fileParts.length && targetParts[firstDifferingIndex] === fileParts[firstDifferingIndex]) firstDifferingIndex++;
+	if (firstDifferingIndex >= targetParts.length && firstDifferingIndex >= fileParts.length) {
+		const targetBasename = path.basename(targetAbs, ".ts");
+		if (targetBasename !== "index") return `./${targetBasename}`;
+		return null;
+	}
+	const firstDifferingSegment = targetParts[firstDifferingIndex];
+	if (!firstDifferingSegment) return null;
+	if (firstDifferingIndex === fileParts.length) return `./${firstDifferingSegment}`;
+	if (firstDifferingIndex === fileParts.length - 1) {
+		if (!(firstDifferingIndex === 0)) return `../${firstDifferingSegment}`;
+	}
+	return `${fileBoundary.alias}/${firstDifferingSegment}`;
+}
+
+//#endregion
+//#region eslint-plugin-import-boundaries/importHandler.ts
+/**
+* Main handler for all import statements.
+* Validates import paths against boundary rules and enforces correct path format.
+*
+* @returns true if a violation was reported, false otherwise
+*/
+function handleImport(options) {
+	const { node, rawSpec, fileDir, fileBoundary, boundaries, rootDir, cwd, context, crossBoundaryStyle = "alias", defaultSeverity, allowUnknownBoundaries = false, isTypeOnly = false, skipBoundaryRules = false } = options;
+	const isRelative = rawSpec.startsWith(".");
+	const matchesBoundaryAlias = boundaries.some((b) => rawSpec === b.alias || rawSpec.startsWith(`${b.alias}/`));
+	const isAbsoluteInRoot = rawSpec.startsWith(rootDir) || rawSpec.startsWith(`/${rootDir}`);
+	if (!isRelative && !matchesBoundaryAlias && !isAbsoluteInRoot) return false;
+	if (crossBoundaryStyle === "alias") {
+		const aliasSubpathCheck = checkAliasSubpath(rawSpec, boundaries);
+		if (aliasSubpathCheck.isSubpath) {
+			const targetBoundary$1 = boundaries.find((b) => b.alias === aliasSubpathCheck.baseAlias);
+			if (targetBoundary$1 && fileBoundary && targetBoundary$1 !== fileBoundary) {
+				const expectedPath = targetBoundary$1.alias;
+				const severity$1 = fileBoundary.severity || defaultSeverity;
+				const reportOptions$1 = {
+					node,
+					messageId: "incorrectImportPath",
+					data: {
+						expectedPath,
+						actualPath: rawSpec
+					},
+					fix: createFixer(node, expectedPath),
+					...severity$1 && { severity: severity$1 === "warn" ? 1 : 2 }
+				};
+				context.report(reportOptions$1);
+				return true;
+			}
+		}
+	}
+	const { targetAbs } = resolveTargetPath(rawSpec, fileDir, boundaries, rootDir, cwd);
+	const targetBoundary = boundaries.find((b) => isInsideDir(b.absDir, targetAbs)) ?? null;
+	if (!skipBoundaryRules && fileBoundary && targetBoundary && fileBoundary !== targetBoundary) {
+		const violation = checkBoundaryRules(fileBoundary, targetBoundary, boundaries, isTypeOnly);
+		if (violation) {
+			const severity$1 = fileBoundary.severity || defaultSeverity;
+			const reportOptions$1 = {
+				node,
+				messageId: "boundaryViolation",
+				data: {
+					from: fileBoundary.alias,
+					to: targetBoundary.alias,
+					reason: violation.reason
+				},
+				...severity$1 && { severity: severity$1 === "warn" ? 1 : 2 }
+			};
+			context.report(reportOptions$1);
+			return true;
+		}
+	}
+	const correctPath = calculateCorrectImportPath(rawSpec, fileDir, fileBoundary, boundaries, rootDir, cwd, crossBoundaryStyle);
+	if (!correctPath) {
+		if (fileBoundary && rawSpec === fileBoundary.alias) {
+			const severity$1 = fileBoundary.severity || defaultSeverity;
+			const reportOptions$1 = {
+				node,
+				messageId: "ancestorBarrelImport",
+				data: { alias: fileBoundary.alias },
+				...severity$1 && { severity: severity$1 === "warn" ? 1 : 2 }
+			};
+			context.report(reportOptions$1);
+			return true;
+		}
+		return false;
+	}
+	if (correctPath === "UNKNOWN_BOUNDARY") {
+		if (!allowUnknownBoundaries) {
+			const reportOptions$1 = {
+				node,
+				messageId: "unknownBoundaryImport",
+				data: { path: rawSpec },
+				...defaultSeverity && { severity: defaultSeverity === "warn" ? 1 : 2 }
+			};
+			context.report(reportOptions$1);
+			return true;
+		}
+		return false;
+	}
+	if (rawSpec === correctPath) return false;
+	const severity = fileBoundary?.severity || defaultSeverity;
+	const reportOptions = {
+		node,
+		messageId: "incorrectImportPath",
+		data: {
+			expectedPath: correctPath,
+			actualPath: rawSpec
+		},
+		fix: createFixer(node, correctPath),
+		...severity && { severity: severity === "warn" ? 1 : 2 }
+	};
+	context.report(reportOptions);
+	return true;
+}
+
+//#endregion
+//#region eslint-plugin-import-boundaries/index.ts
+const rule = {
+	meta: {
+		type: "problem",
+		fixable: "code",
+		docs: {
+			description: "Enforces architectural boundaries with deterministic import path rules: cross-boundary uses alias without subpath, siblings use relative, boundary-root and top-level paths use alias, cousins use relative (max one ../).",
+			recommended: false
+		},
+		schema: [{
+			type: "object",
+			properties: {
+				rootDir: { type: "string" },
+				boundaries: {
+					type: "array",
+					items: {
+						type: "object",
+						properties: {
+							dir: { type: "string" },
+							alias: { type: "string" },
+							allowImportsFrom: {
+								type: "array",
+								items: { type: "string" }
+							},
+							denyImportsFrom: {
+								type: "array",
+								items: { type: "string" }
+							},
+							allowTypeImportsFrom: {
+								type: "array",
+								items: { type: "string" }
+							},
+							nestedPathFormat: {
+								type: "string",
+								enum: [
+									"alias",
+									"relative",
+									"inherit"
+								]
+							},
+							severity: {
+								type: "string",
+								enum: ["error", "warn"]
+							}
+						},
+						required: ["dir", "alias"]
+					},
+					minItems: 1
+				},
+				crossBoundaryStyle: {
+					type: "string",
+					enum: ["alias", "absolute"],
+					default: "alias"
+				},
+				defaultSeverity: {
+					type: "string",
+					enum: ["error", "warn"]
+				},
+				allowUnknownBoundaries: {
+					type: "boolean",
+					default: false
+				},
+				skipBoundaryRulesForTestFiles: {
+					type: "boolean",
+					default: true
+				}
+			},
+			required: ["boundaries"]
+		}],
+		messages: {
+			incorrectImportPath: "Expected '{{expectedPath}}' but got '{{actualPath}}'.",
+			ancestorBarrelImport: "Cannot import from ancestor barrel '{{alias}}'. This would create a circular dependency. Import from the specific file or directory instead.",
+			unknownBoundaryImport: "Cannot import from '{{path}}' - path is outside all configured boundaries. Add this path to boundaries configuration or set 'allowUnknownBoundaries: true'.",
+			boundaryViolation: "Cannot import from '{{to}}' to '{{from}}': {{reason}}"
+		}
+	},
+	create(context) {
+		if (!context.options || context.options.length === 0) throw new Error("boundary-alias-vs-relative requires boundaries configuration");
+		const { rootDir = "src", boundaries, crossBoundaryStyle = "alias", defaultSeverity, allowUnknownBoundaries = false, skipBoundaryRulesForTestFiles = true } = context.options[0];
+		const cwd = context.getCwd?.() ?? process.cwd();
+		const resolvedBoundaries = boundaries.map((b) => ({
+			dir: b.dir,
+			alias: b.alias,
+			absDir: path.resolve(cwd, rootDir, b.dir),
+			allowImportsFrom: b.allowImportsFrom,
+			denyImportsFrom: b.denyImportsFrom,
+			allowTypeImportsFrom: b.allowTypeImportsFrom,
+			nestedPathFormat: b.nestedPathFormat,
+			severity: b.severity
+		}));
+		let cachedFileData = null;
+		/**
+		* Get metadata about the current file being linted.
+		* Results are cached per file to avoid recomputation.
+		*
+		* @returns FileData with directory and boundary information, or { isValid: false } if file path is invalid
+		*/
+		function getFileDataCached() {
+			if (cachedFileData) return cachedFileData;
+			cachedFileData = getFileData(context.filename ?? context.getFilename?.() ?? "<unknown>", resolvedBoundaries);
+			return cachedFileData;
+		}
+		/**
+		* Wrapper function that prepares file data and calls the main import handler.
+		*
+		* @param node - AST node for the import (ImportDeclaration, ImportExpression, or CallExpression)
+		* @param rawSpec - Raw import specifier string (e.g., '@entities', './file', '../parent')
+		* @param isTypeOnly - Whether this is a type-only import (TypeScript)
+		*/
+		function handleImportStatement(node, rawSpec, isTypeOnly = false) {
+			const fileData = getFileDataCached();
+			if (!fileData.isValid) return;
+			const { fileDir, fileBoundary } = fileData;
+			if (!fileDir) return;
+			handleImport({
+				node,
+				rawSpec,
+				fileDir,
+				fileBoundary: fileBoundary ?? null,
+				boundaries: resolvedBoundaries,
+				rootDir,
+				cwd,
+				context,
+				crossBoundaryStyle,
+				defaultSeverity,
+				allowUnknownBoundaries,
+				isTypeOnly,
+				skipBoundaryRules: skipBoundaryRulesForTestFiles
+			});
+		}
+		return {
+			Program() {
+				cachedFileData = null;
+			},
+			ImportDeclaration(node) {
+				const spec = node.source?.value;
+				if (typeof spec === "string") handleImportStatement(node, spec, node.importKind === "type");
+			},
+			ImportExpression(node) {
+				const arg = node.source;
+				if (arg?.type === "Literal" && typeof arg.value === "string") handleImportStatement(node, arg.value, false);
+			},
+			CallExpression(node) {
+				if (node.callee.type === "Identifier" && node.callee.name === "require" && node.arguments.length === 1 && node.arguments[0]?.type === "Literal" && typeof node.arguments[0].value === "string") handleImportStatement(node, node.arguments[0].value, false);
+			},
+			ExportNamedDeclaration(node) {
+				const spec = node.source?.value;
+				if (typeof spec === "string") handleImportStatement(node, spec, node.exportKind === "type");
+			},
+			ExportAllDeclaration(node) {
+				const spec = node.source?.value;
+				if (typeof spec === "string") handleImportStatement(node, spec, node.exportKind === "type");
+			}
+		};
+	}
+};
+var eslint_plugin_import_boundaries_default = { rules: { enforce: rule } };
+
+//#endregion
+export { eslint_plugin_import_boundaries_default as default };

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "eslint-plugin-import-boundaries",
+  "version": "0.1.0",
+  "description": "Enforce architectural boundaries with deterministic import paths",
+  "type": "module",
+  "main": "./eslint-plugin-import-boundaries.js",
+  "exports": {
+    ".": {
+      "import": "./eslint-plugin-import-boundaries.js"
+    }
+  },
+  "files": [
+    "eslint-plugin-import-boundaries.js",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "eslint",
+    "eslint-plugin",
+    "eslint-rule",
+    "import",
+    "boundaries",
+    "architecture",
+    "clean-architecture",
+    "hexagonal-architecture",
+    "barrel-files",
+    "deterministic",
+    "import-paths"
+  ],
+  "author": "ClassicalMoser",
+  "license": "ISC",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ClassicalMoser/eslint-plugin-import-boundaries.git"
+  },
+  "bugs": {
+    "url": "https://github.com/ClassicalMoser/eslint-plugin-import-boundaries/issues"
+  },
+  "homepage": "https://github.com/ClassicalMoser/eslint-plugin-import-boundaries#readme",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "peerDependencies": {
+    "eslint": ">=9.0.0"
+  },
+  "scripts": {
+    "build": "tsdown --config tsdown.config.ts",
+    "test": "vitest run",
+    "test:watch": "vitest watch",
+    "test:coverage": "vitest run --coverage",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "format": "prettier --write .",
+    "prepublishOnly": "npm run build && npm run test && npm run typecheck"
+  },
+  "devDependencies": {
+    "@antfu/eslint-config": "^6.4.2",
+    "@rolldown/binding-darwin-x64": "1.0.0-beta.53",
+    "@types/node": "^24.10.1",
+    "@vitest/coverage-v8": "^4.0.15",
+    "eslint": "^9.39.1",
+    "eslint-config-prettier": "^10.1.8",
+    "prettier": "^3.7.4",
+    "tsdown": "0.17.0",
+    "typescript": "^5.9.3",
+    "vitest": "4.0.15"
+  }
+}