@dword-design/eslint-plugin-import-alias 6.0.3 → 8.0.0

package/README.md

@@ -85,7 +85,9 @@ $ yarn add @dword-design/eslint-plugin-import-alias
 
 Add the plugin to your ESLint config:
 
-```js
+```ts
+// eslint.config.ts
+
 import { defineConfig } from 'eslint/config';
 import importAlias from '@dword-design/import-alias';
 
@@ -94,9 +96,37 @@ export default defineConfig([
 ]);
 ```
 
-Alright, now you have to tell the plugin which aliases to use. In the simplest case, you are already using [babel-plugin-module-resolver](https://www.npmjs.com/package/babel-plugin-module-resolver) for your aliases. Your babel config would look something like this:
+Options can be passed by setting them in the `prefer-alias` rule:
+
+```ts
+// eslint.config.ts
+
+import { defineConfig } from 'eslint/config';
+import importAlias from '@dword-design/import-alias';
+
+export default defineConfig([
+  importAlias.configs.recommended,
+  {
+    rules: {
+      '@dword-design/import-alias/prefer-alias': ['error', /* options */],
+    },
+  },
+]);
+```
+
+Now you have multiple ways to tell the plugin about aliases.
+
+### `tsconfig.json` `paths` setting
+
+If you are a TypeScript user and you have aliases configured in your `tsconfig.json` via the `paths` setting, they will automatically be loaded. You can disable this behavior by setting `shouldReadTsConfig` to `false` in the plugin options.
+
+### [babel-plugin-module-resolver](https://www.npmjs.com/package/babel-plugin-module-resolver)
+
+If you are already using [babel-plugin-module-resolver](https://www.npmjs.com/package/babel-plugin-module-resolver), the plugin will load the Babel config and extract the `alias` and `resolvePath` options. You can disable this behavior by setting `shouldReadBabelConfig` to `false` in the plugin options.
 
 ```json
+// .babelrc.json
+
 {
   "plugins": {
     ["module-resolver", {
@@ -108,32 +138,54 @@ Alright, now you have to tell the plugin which aliases to use. In the simplest c
 }
 ```
 
-In this case lucky you, you don't have to do anything else. The plugin should work out of the box.
+### Plugin `alias` option
 
-If you have a special project setup that does not have a babel config in the project path, you can still use the plugin by passing the aliases directly to the rule. In this case you define the rule additionally in the `rules` section:
+You can also just pass the aliases to the plugin as an option.
 
-```json
-"rules": {
-  "@dword-design/import-alias/prefer-alias": [
-    "error",
-    {
-      "alias": {
-        "@": "./src",
-        "@components": "./src/components"
-      }
-    }
-  ]
-}
+```ts
+// eslint.config.ts
+
+import { defineConfig } from 'eslint/config';
+import importAlias from '@dword-design/import-alias';
+
+export default defineConfig([
+  importAlias.configs.recommended,
+  {
+    rules: {
+      '@dword-design/import-alias/prefer-alias': [
+        'error',
+        {
+          'alias': {
+            '@': './src',
+            '@components': './src/components',
+          },
+        },
+      ],
+    },
+  },
+]);
 ```
 
+## Alias resolution
+
 By default, the plugin will convert parent paths to aliases (like `../model/foo`), but will keep subpath imports relative. You can change that to also convert subpaths to aliased imports by passing the `aliasForSubpaths` option to the rule like so:
 
-```json
-"rules": {
-  "@dword-design/import-alias/prefer-alias": ["error", { "aliasForSubpaths": true }]
+```ts
+rules: {
+  '@dword-design/import-alias/prefer-alias': ['error', { aliasForSubpaths: true }],
+}
+```
+
+Also, inner alias paths are preferred to outer ones. Example:
+
+```ts
+rules: {
+  '@dword-design/import-alias/prefer-alias': ['error', { alias: { '@': './app', '@@': '.' }],
 }
 ```
 
+If an import resolves to a file insode `app`, `@` will be preferred over `@@` although both aliases match. This is convenient for the use case where you have a lot of aliases for top-level folders like `components`, `utils` etc where you usually want those instead of a generic root alias. If you have other use cases, please let me know.
+
 <!-- LICENSE/ -->
 ## Contribute
 

package/dist/babel-plugin-module-resolver.d.ts

@@ -0,0 +1,18 @@
+declare module 'babel-plugin-module-resolver' {
+  export function resolvePath(
+    sourcePath: string,
+    currentFile: string,
+    options: { alias?: Record<string, string>; cwd?: string },
+  ): string;
+}
+declare module '@babel/core' {
+  export type BabelPlugin = { key: string; options?: Record<string, unknown> };
+
+  export interface BabelConfig {
+    plugins?: BabelPlugin[];
+  }
+
+  export function loadOptions(
+    options?: Record<string, unknown>,
+  ): BabelConfig | null;
+}

package/dist/index.d.ts

@@ -0,0 +1,18 @@
+declare const _default: {
+    configs: {
+        recommended: {
+            plugins: {
+                '@dword-design/import-alias': {
+                    rules: {
+                        'prefer-alias': import("@typescript-eslint/utils/dist/ts-eslint").RuleModule<"parentImport" | "subpathImport", [import("./rules/prefer-alias").OptionsInput], unknown, import("@typescript-eslint/utils/dist/ts-eslint").RuleListener>;
+                    };
+                };
+            };
+            rules: {
+                '@dword-design/import-alias/prefer-alias': string;
+            };
+        };
+    };
+};
+export default _default;
+export { type OptionsInput } from './rules/prefer-alias';

package/dist/index.js

@@ -1,10 +1,18 @@
-import preferAlias from './rules/prefer-alias.js';
-const plugin = { rules: { 'prefer-alias': preferAlias } };
-export default {
-    configs: {
-        recommended: {
-            plugins: { '@dword-design/import-alias': plugin },
-            rules: { '@dword-design/import-alias/prefer-alias': 'error' },
-        },
-    },
+import preferAlias from "./rules/prefer-alias.js";
+const plugin = {
+  rules: {
+    "prefer-alias": preferAlias
+  }
 };
+export default {
+  configs: {
+    recommended: {
+      plugins: {
+        "@dword-design/import-alias": plugin
+      },
+      rules: {
+        "@dword-design/import-alias/prefer-alias": "error"
+      }
+    }
+  }
+};

package/dist/rules/prefer-alias.d.ts

@@ -0,0 +1,21 @@
+import { loadOptions } from '@babel/core';
+import { ESLintUtils } from '@typescript-eslint/utils';
+export interface BabelPluginModuleResolverOptions {
+    alias?: Record<string, string>;
+    cwd?: string;
+    resolvePath?: (sourcePath: string, currentFile: string, options: Pick<BabelPluginModuleResolverOptions, 'alias' | 'cwd'>) => string;
+}
+export interface Options {
+    alias: Record<string, string>;
+    aliasForSubpaths: boolean;
+    shouldReadTsConfig: boolean;
+    shouldReadBabelConfig: boolean;
+    resolvePath: (sourcePath: string, currentFile: string, options: Pick<BabelPluginModuleResolverOptions, 'alias' | 'cwd'>) => string;
+    cwd: string;
+}
+type BabelOptions = Exclude<Parameters<typeof loadOptions>[0], undefined>;
+export type OptionsInput = Partial<Options> & {
+    babelOptions?: BabelOptions;
+};
+declare const _default: ESLintUtils.RuleModule<"parentImport" | "subpathImport", [OptionsInput], unknown, ESLintUtils.RuleListener>;
+export default _default;

package/dist/rules/prefer-alias.js

@@ -1,87 +1,164 @@
-import pathLib from 'node:path';
-import { loadOptions } from '@babel/core';
-import defu from '@dword-design/defu';
-import { resolvePath as defaultResolvePath } from 'babel-plugin-module-resolver';
+import pathLib from "node:path";
+import { loadOptions } from "@babel/core";
+import defaults from "@dword-design/defaults";
+import { ESLintUtils } from "@typescript-eslint/utils";
+import { resolvePath as defaultResolvePath } from "babel-plugin-module-resolver";
+import { omit, orderBy, pick } from "lodash-es";
+const ts = await import("typescript").then(module => module.default).catch(() => null);
+const loadTsConfigPaths = (currentFile, cwd) => {
+  if (!ts) {
+    return {};
+  }
+  const configPath = ts.findConfigFile(pathLib.dirname(currentFile), ts.sys.fileExists, "tsconfig.json");
+  if (!configPath) {
+    return {};
+  }
+  const configText = ts.sys.readFile(configPath);
+  if (!configText) {
+    return {};
+  }
+  const result = ts.parseConfigFileTextToJson(configPath, configText);
+  if (!result.config) {
+    return {};
+  }
+  const parsedConfig = ts.parseJsonConfigFileContent(result.config, ts.sys, pathLib.dirname(configPath), void 0, configPath);
+  const {
+    baseUrl,
+    paths
+  } = parsedConfig.options;
+  if (!paths) {
+    return {};
+  }
+  const aliases = {};
+  const basePath = baseUrl ? pathLib.resolve(pathLib.dirname(configPath), baseUrl) : pathLib.dirname(configPath);
+  return Object.fromEntries(Object.entries(paths).map(([key, values]) => {
+    const aliasKey = key.replace(/\/\*$/, "");
+    const absoluteAliasPath = pathLib.resolve(basePath, values[0].replace(/\/\*$/, ""));
+    const relativeAliasPath = pathLib.relative(cwd, absoluteAliasPath);
+    return [aliasKey, `./${relativeAliasPath}`];
+  }));
+  return aliases;
+};
+const createRule = ESLintUtils.RuleCreator(() => "");
 const isParentImport = path => /^(\.\/)?\.\.\//.test(path);
 const findMatchingAlias = (sourcePath, currentFile, options) => {
-    const resolvePath = options.resolvePath || defaultResolvePath;
-    const absoluteSourcePath = pathLib.resolve(pathLib.dirname(currentFile), sourcePath);
-    for (const aliasName of Object.keys(options.alias)) {
-        const path = pathLib.resolve(pathLib.dirname(currentFile), resolvePath(`${aliasName}/`, currentFile, options));
-        if (absoluteSourcePath.startsWith(path)) {
-            return { name: aliasName, path };
-        }
+  const absoluteSourcePath = pathLib.resolve(pathLib.dirname(currentFile), sourcePath);
+  const matches = Object.keys(options.alias).map(aliasName => {
+    const path = pathLib.resolve(pathLib.dirname(currentFile), options.resolvePath(`${aliasName}/`, currentFile, pick(options, ["alias", "cwd"])));
+    if (absoluteSourcePath.startsWith(path)) {
+      return {
+        name: aliasName,
+        path,
+        segmentCount: path.split(pathLib.sep).length
+      };
     }
+    return null;
+  }).filter(match => !!match);
+  const sortedMatches = orderBy(matches, ["segmentCount"], ["desc"]);
+  return sortedMatches?.[0] ?? null;
 };
-export default {
-    create: context => {
-        const currentFile = context.getFilename();
-        const folder = pathLib.dirname(currentFile);
-        // can't check a non-file
-        if (currentFile === '<text>')
-            return {};
-        const optionsFromRule = context.options[0] ?? {};
-        const babelConfig = (loadOptions({
-            filename: currentFile,
-            ...optionsFromRule.babelOptions,
-        }) || {});
-        const optionsFromPlugin = babelConfig?.plugins?.find(_ => _.key === 'module-resolver')?.options ??
-            {};
-        const options = defu(optionsFromRule, optionsFromPlugin, {
-            alias: [],
-            cwd: context.cwd,
-        });
-        if (options.alias.length === 0) {
-            throw new Error('No alias configured. You have to define aliases by either passing them to the babel-plugin-module-resolver plugin in your Babel config, or directly to the prefer-alias rule.');
+export default createRule({
+  create: context => {
+    const currentFile = context.getFilename();
+    const folder = pathLib.dirname(currentFile);
+    if (currentFile === "<text>") return {};
+    const optionsFromRule = defaults(context.options[0] ?? {}, {
+      babelOptions: {},
+      shouldReadBabelConfig: true,
+      shouldReadTsConfig: true
+    });
+    const optionsFromBabelPlugin = optionsFromRule.shouldReadBabelConfig ? (() => {
+      const babelConfig = loadOptions({
+        filename: currentFile,
+        ...optionsFromRule.babelOptions
+      });
+      const babelPlugin = babelConfig?.plugins?.find?.(iteratedPlugin => iteratedPlugin.key === "module-resolver") ?? null;
+      const babelPluginOptions = babelPlugin?.options ?? {};
+      return pick(babelPluginOptions, ["alias", "resolvePath"]);
+    })() : {};
+    const options = defaults(omit(optionsFromRule, ["babelOptions"]), {
+      alias: optionsFromRule.shouldReadTsConfig ? loadTsConfigPaths(currentFile, context.cwd) : {}
+    }, optionsFromBabelPlugin, {
+      alias: {},
+      aliasForSubpaths: false,
+      cwd: context.cwd,
+      resolvePath: defaultResolvePath
+    });
+    if (Object.keys(options.alias).length === 0) {
+      throw new Error("No alias configured. You have to define aliases by either passing them to the babel-plugin-module-resolver plugin in your Babel config, defining them in your tsconfig.json paths, or passing them directly to the prefer-alias rule.");
+    }
+    return {
+      ImportDeclaration: node => {
+        const sourcePath = node.source.value;
+        const hasAlias = Object.keys(options.alias).some(alias => sourcePath.startsWith(`${alias}/`));
+        if (isParentImport(sourcePath)) {
+          const matchingAlias = findMatchingAlias(sourcePath, currentFile, options);
+          if (!matchingAlias) {
+            return;
+          }
+          const absoluteImportPath = pathLib.resolve(folder, sourcePath);
+          const rewrittenImport = `${matchingAlias.name}/${pathLib.relative(matchingAlias.path, absoluteImportPath).replaceAll("\\", "/")}`;
+          return context.report({
+            data: {
+              rewrittenImport,
+              sourcePath
+            },
+            fix: fixer => fixer.replaceTextRange([node.source.range[0] + 1, node.source.range[1] - 1], rewrittenImport),
+            messageId: "parentImport",
+            node
+          });
         }
-        const resolvePath = options.resolvePath || defaultResolvePath;
-        return {
-            ImportDeclaration: node => {
-                const sourcePath = node.source.value;
-                const hasAlias = Object.keys(options.alias).some(alias => sourcePath.startsWith(`${alias}/`));
-                // relative parent
-                if (isParentImport(sourcePath)) {
-                    const matchingAlias = findMatchingAlias(sourcePath, currentFile, options);
-                    if (!matchingAlias) {
-                        return;
-                    }
-                    const absoluteImportPath = pathLib.resolve(folder, sourcePath);
-                    const rewrittenImport = `${matchingAlias.name}/${pathLib
-                        .relative(matchingAlias.path, absoluteImportPath)
-                        .replaceAll('\\', '/')}`;
-                    return context.report({
-                        fix: fixer => fixer.replaceTextRange([node.source.range[0] + 1, node.source.range[1] - 1], rewrittenImport),
-                        message: `Unexpected parent import '${sourcePath}'. Use '${rewrittenImport}' instead`,
-                        node,
-                    });
-                }
-                const importWithoutAlias = resolvePath(sourcePath, currentFile, options);
-                if (!isParentImport(importWithoutAlias) &&
-                    hasAlias &&
-                    !options.aliasForSubpaths) {
-                    return context.report({
-                        fix: fixer => fixer.replaceTextRange([node.source.range[0] + 1, node.source.range[1] - 1], importWithoutAlias),
-                        message: `Unexpected subpath import via alias '${sourcePath}'. Use '${importWithoutAlias}' instead`,
-                        node,
-                    });
-                }
-                return;
+        const importWithoutAlias = options.resolvePath(sourcePath, currentFile, options);
+        if (!isParentImport(importWithoutAlias) && hasAlias && !options.aliasForSubpaths) {
+          return context.report({
+            data: {
+              rewrittenImport: importWithoutAlias,
+              sourcePath
             },
-        };
+            fix: fixer => fixer.replaceTextRange([node.source.range[0] + 1, node.source.range[1] - 1], importWithoutAlias),
+            messageId: "subpathImport",
+            node
+          });
+        }
+        return;
+      }
+    };
+  },
+  defaultOptions: [{}],
+  meta: {
+    docs: {
+      description: "Enforce usage of import aliases over relative parent imports"
     },
-    meta: {
-        fixable: true,
-        schema: [
-            {
-                additionalProperties: false,
-                properties: {
-                    alias: { type: 'object' },
-                    aliasForSubpaths: { default: false, type: 'boolean' },
-                    babelOptions: { type: 'object' },
-                },
-                type: 'object',
-            },
-        ],
-        type: 'suggestion',
+    fixable: "code",
+    messages: {
+      parentImport: "Unexpected parent import '{{sourcePath}}'. Use '{{rewrittenImport}}' instead",
+      subpathImport: "Unexpected subpath import via alias '{{sourcePath}}'. Use '{{rewrittenImport}}' instead"
     },
-};
+    schema: [{
+      additionalProperties: false,
+      properties: {
+        alias: {
+          type: "object"
+        },
+        aliasForSubpaths: {
+          default: false,
+          type: "boolean"
+        },
+        babelOptions: {
+          type: "object"
+        },
+        shouldReadBabelConfig: {
+          default: true,
+          type: "boolean"
+        },
+        shouldReadTsConfig: {
+          default: true,
+          type: "boolean"
+        }
+      },
+      type: "object"
+    }],
+    type: "suggestion"
+  },
+  name: "prefer-alias"
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dword-design/eslint-plugin-import-alias",
-  "version": "6.0.3",
+  "version": "8.0.0",
   "description": "An ESLint plugin that enforces the use of import aliases. Also supports autofixing.",
   "keywords": [
     "alias",
@@ -28,7 +28,12 @@
   "license": "MIT",
   "author": "Sebastian Landwehr <info@sebastianlandwehr.com>",
   "type": "module",
-  "exports": "./dist/index.js",
+  "exports": {
+    ".": {
+      "default": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
   "main": "dist/index.js",
   "files": [
     "dist"
@@ -41,26 +46,40 @@
     "lint": "base lint",
     "prepare": "base prepare",
     "prepublishOnly": "base prepublishOnly",
-    "test": "base test"
+    "test": "base test",
+    "typecheck": "base typecheck",
+    "verify": "base verify"
   },
   "dependencies": {
-    "@babel/core": "^7.27.4",
-    "@dword-design/defu": "^1.0.0",
+    "@babel/core": "^7.28.5",
+    "@dword-design/defaults": "^1.1.1",
+    "@types/babel__core": "^7.20.5",
+    "@types/lodash-es": "^4.17.12",
+    "@typescript-eslint/utils": "^8.50.1",
     "babel-plugin-module-resolver": "^5.0.2"
   },
   "devDependencies": {
-    "@dword-design/base": "^13.0.1",
-    "@playwright/test": "^1.52.0",
-    "depcheck-package-name": "^3.0.1",
-    "endent": "npm:@dword-design/endent@^1.4.1",
-    "eslint": "^9.28.0",
-    "lodash-es": "^4.17.21",
-    "output-files": "^2.0.32",
-    "typescript-eslint": "^8.33.1"
+    "@dword-design/base": "^16.1.7",
+    "@playwright/test": "^1.57.0",
+    "depcheck-package-name": "^5.0.0",
+    "endent": "npm:@dword-design/endent@^1.4.7",
+    "eslint": "^9.39.2",
+    "lodash-es": "^4.17.22",
+    "output-files": "^3.0.0",
+    "typescript": "^5.0.0",
+    "typescript-eslint": "^8.50.0"
+  },
+  "peerDependencies": {
+    "typescript": ">=5.0.0"
+  },
+  "peerDependenciesMeta": {
+    "typescript": {
+      "optional": true
+    }
   },
   "packageManager": "pnpm@10.11.1+sha512.e519b9f7639869dc8d5c3c5dfef73b3f091094b0a006d7317353c72b124e80e1afd429732e28705ad6bfa1ee879c1fce46c128ccebd3192101f43dd67c667912",
   "engines": {
-    "node": ">=18"
+    "node": ">=22"
   },
   "publishConfig": {
     "access": "public"