eslint-plugin-import-boundaries 0.1.2 → 0.2.0

package/README.md

@@ -5,17 +5,19 @@
 [![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.**
+**Note: This is a beta release, originally developed for a personal project. It is not yet stable and may have breaking changes.**
 
 An opinionated 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.
 
+**Important:** This rule expects an index or barrel file at every directory level. This barrel file represents the external accessibility of the module as a boundary interface, enabling zero I/O path resolution.
+
 ## 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 yet implemented)
-- **Auto-fixable**: Most violations are automatically fixable
+- **Readable Paths**: Always resolves to the most readable filepath (no `../../../../../../` chains)
+- **Architectural Boundaries**: Enforce clean architecture, hexagonal architecture, feature-sliced design, or any other boundary pattern (including nested boundaries)
+- **Auto-fixable**: Legal import paths are auto-fixable and will always converge to the correct import string.
 - **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
@@ -128,6 +130,41 @@ import { Database } from "@infrastructure";
 // Error: Cannot import from '@infrastructure' to '@application': Import not allowed
 ```
 
+#### Nested Boundaries
+
+Boundaries can be nested, and each boundary must explicitly declare its import rules:
+
+```javascript
+{
+  boundaries: [
+    {
+      dir: 'application',
+      alias: '@application',
+      allowImportsFrom: ['@domain'],
+    },
+    {
+      dir: 'application/ports',
+      alias: '@ports',
+      allowImportsFrom: ['@infrastructure', '@domain'], // Can import from infrastructure even though parent cannot
+    },
+    {
+      dir: 'interface',
+      alias: '@interface',
+      allowImportsFrom: ['@application', '@public-use-cases'],
+      denyImportsFrom: ['@use-cases'], // Can allow parent and specific child, but deny intermediate boundary
+    },
+  ],
+}
+```
+
+**Key behaviors:**
+
+- Each boundary must explicitly declare its rules (no inheritance)
+- Files in boundaries without rules resolve to their nearest ancestor with rules (or are rejected if no ancestor has rules)
+- Rules work the same regardless of nesting depth (flat rule checking)
+- You can selectively allow/deny specific nested boundaries
+- A boundary is considered to have rules if it defines `allowImportsFrom`, `denyImportsFrom`, or `allowTypeImportsFrom` (even if empty arrays)
+
 ### 4. Type-Only Imports
 
 Different rules for types vs values (types don't create runtime dependencies):
@@ -178,6 +215,7 @@ import { something } from "@application"; // When inside @application boundary
       dir: 'domain',                // Required: Relative directory path
       alias: '@domain',             // Required when crossBoundaryStyle is 'alias', optional when 'absolute'
       denyImportsFrom: ['@application', '@infrastructure', '@interface', '@composition'], // Domain is pure
+      severity: 'error',             // Optional: 'error' | 'warn' (overrides defaultSeverity for this boundary)
     },
     {
       dir: 'application',
@@ -316,9 +354,9 @@ This plugin uses a different approach:
 
 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
+## Examples
 
-- **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.
+See [Hexagonal Architecture Defaults](./HEXAGONAL_DEFAULTS.md) for a complete example configuration for hexagonal architecture (ports and adapters) projects.
 
 ## License
 

package/eslint-plugin-import-boundaries.js

@@ -87,6 +87,21 @@ function checkAliasSubpath(spec, boundaries) {
 	return { isSubpath: false };
 }
 /**
+* Resolve a file to the nearest boundary that has rules specified.
+* If no boundaries with rules are found, returns null.
+*
+* @param filename - Absolute filename
+* @param boundaries - Array of all boundaries
+* @returns The nearest boundary with rules, or null if none found
+*/
+function resolveToSpecifiedBoundary(filename, boundaries) {
+	const specifiedBoundaries = boundaries.filter((b) => isInsideDir(b.absDir, filename)).filter((b) => b.allowImportsFrom !== void 0 || b.denyImportsFrom !== void 0 || b.allowTypeImportsFrom !== void 0);
+	if (specifiedBoundaries.length > 0) return specifiedBoundaries.sort((a, b) => b.absDir.length - a.absDir.length)[0];
+	const ancestors = boundaries.filter((b) => b.allowImportsFrom !== void 0 || b.denyImportsFrom !== void 0 || b.allowTypeImportsFrom !== void 0).filter((b) => isInsideDir(b.absDir, filename));
+	if (ancestors.length > 0) return ancestors.sort((a, b) => b.absDir.length - a.absDir.length)[0];
+	return null;
+}
+/**
 * Get metadata about the current file being linted.
 * Results are cached per file to avoid recomputation.
 *
@@ -96,12 +111,10 @@ function checkAliasSubpath(spec, boundaries) {
 */
 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
+		fileDir: path.dirname(filename),
+		fileBoundary: resolveToSpecifiedBoundary(filename, boundaries)
 	};
 }
 
@@ -273,7 +286,7 @@ function calculateCorrectImportPath(rawSpec, fileDir, fileBoundary, boundaries,
 	".cjs"
 ]) {
 	const { targetAbs, targetDir } = resolveTargetPath(rawSpec, fileDir, boundaries, rootDir, cwd, barrelFileName, fileExtensions);
-	const targetBoundary = boundaries.find((b) => isInsideDir(b.absDir, targetAbs)) ?? null;
+	const targetBoundary = resolveToSpecifiedBoundary(targetAbs, boundaries);
 	if (!fileBoundary || targetBoundary !== fileBoundary) {
 		if (targetBoundary) {
 			if (crossBoundaryStyle === "absolute") return path.join(rootDir, targetBoundary.dir).replace(/\\/g, "/");
@@ -358,7 +371,7 @@ function handleImport(options) {
 			}
 		}
 	}
-	const targetBoundary = boundaries.find((b) => isInsideDir(b.absDir, targetAbs)) ?? null;
+	const targetBoundary = resolveToSpecifiedBoundary(targetAbs, boundaries);
 	if (!skipBoundaryRules && fileBoundary && targetBoundary && fileBoundary !== targetBoundary) {
 		const violation = checkBoundaryRules(fileBoundary, targetBoundary, boundaries, isTypeOnly);
 		if (violation) {

package/package.json

@@ -1,22 +1,18 @@
 {
   "name": "eslint-plugin-import-boundaries",
-  "version": "0.1.2",
-  "description": "Enforce architectural boundaries with deterministic import paths",
   "type": "module",
-  "main": "./eslint-plugin-import-boundaries.js",
-  "types": "./eslint-plugin-import-boundaries.d.ts",
-  "exports": {
-    ".": {
-      "import": "./eslint-plugin-import-boundaries.js",
-      "types": "./eslint-plugin-import-boundaries.d.ts"
-    }
+  "version": "0.2.0",
+  "description": "Enforce architectural boundaries with deterministic import paths",
+  "author": "ClassicalMoser",
+  "license": "ISC",
+  "homepage": "https://github.com/ClassicalMoser/eslint-plugin-import-boundaries#readme",
+  "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"
   },
-  "files": [
-    "eslint-plugin-import-boundaries.js",
-    "eslint-plugin-import-boundaries.d.ts",
-    "README.md",
-    "LICENSE"
-  ],
   "keywords": [
     "eslint",
     "eslint-plugin",
@@ -30,22 +26,23 @@
     "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"
+  "exports": {
+    ".": {
+      "types": "./eslint-plugin-import-boundaries.d.ts",
+      "import": "./eslint-plugin-import-boundaries.js"
+    }
   },
-  "homepage": "https://github.com/ClassicalMoser/eslint-plugin-import-boundaries#readme",
+  "main": "./eslint-plugin-import-boundaries.js",
+  "types": "./eslint-plugin-import-boundaries.d.ts",
+  "files": [
+    "LICENSE",
+    "README.md",
+    "eslint-plugin-import-boundaries.d.ts",
+    "eslint-plugin-import-boundaries.js"
+  ],
   "engines": {
     "node": ">=18.0.0"
   },
-  "peerDependencies": {
-    "eslint": ">=9.0.0"
-  },
   "scripts": {
     "build": "tsdown --config tsdown.config.ts",
     "test": "vitest run",
@@ -55,8 +52,14 @@
     "lint": "eslint .",
     "lint:fix": "eslint . --fix",
     "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "validate:fix": "pnpm run lint:fix && pnpm run format && pnpm run typecheck",
+    "validate:check": "pnpm run lint && pnpm run format:check && pnpm run typecheck",
     "prepublishOnly": "npm run build && npm run test && npm run typecheck"
   },
+  "peerDependencies": {
+    "eslint": ">=9.0.0"
+  },
   "devDependencies": {
     "@antfu/eslint-config": "^6.4.2",
     "@rolldown/binding-darwin-x64": "1.0.0-beta.53",