feat(extensions): support pathGroupOverrides and fix options (#327)

JounQin · Xunnamius · stephenjason89 · web-flow · commit 90c1cd01653d · 2025-05-18T02:14:55.000+08:00
Co-authored-by: "Xunnamius (Romulus)" &lt;Xunnamius@users.noreply.github.com&gt;
Co-authored-by: Stephen Jason Wang &lt;stephenjasonwang@gmail.com&gt;
Co-authored-by: autofix-ci[bot] &lt;114827586+autofix-ci[bot]@users.noreply.github.com&gt;
diff --git a/.changeset/fast-bees-talk.md b/.changeset/fast-bees-talk.md
@@ -0,0 +1,5 @@
+---
+"eslint-plugin-import-x": minor
+---
+
+feat(extensions): support `pathGroupOverrides` and `fix` options
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -21,14 +21,16 @@ jobs:
           - 18
           - 20
           - 22
+          - 24
         eslint:
           - 8.56
           - 8
           - 9
 
         include:
           - executeLint: true
-            node: 20
+            node: 22
+            eslint: 9
             os: ubuntu-latest
       fail-fast: false
 
diff --git a/README.md b/README.md
@@ -259,7 +259,7 @@ export default [
 | [consistent-type-specifier-style](docs/rules/consistent-type-specifier-style.md) | Enforce or ban the use of inline type-only markers for named imports.       |     |       |     | 🔧  |     |     |
 | [dynamic-import-chunkname](docs/rules/dynamic-import-chunkname.md)               | Enforce a leading comment with the webpackChunkName for dynamic imports.    |     |       |     |     | 💡  |     |
 | [exports-last](docs/rules/exports-last.md)                                       | Ensure all exports appear after other statements.                           |     |       |     |     |     |     |
-| [extensions](docs/rules/extensions.md)                                           | Ensure consistent use of file extension within the import path.             |     |       |     |     |     |     |
+| [extensions](docs/rules/extensions.md)                                           | Ensure consistent use of file extension within the import path.             |     |       |     | 🔧  | 💡  |     |
 | [first](docs/rules/first.md)                                                     | Ensure all imports appear before other statements.                          |     |       |     | 🔧  |     |     |
 | [group-exports](docs/rules/group-exports.md)                                     | Prefer named exports to be grouped together in a single export declaration. |     |       |     |     |     |     |
 | [imports-first](docs/rules/imports-first.md)                                     | Replaced by `import-x/first`.                                               |     |       |     | 🔧  |     | ❌  |
@@ -700,7 +700,6 @@ Detailed changes for each release are documented in [CHANGELOG.md](./CHANGELOG.m
 [`eslint_d`]: https://www.npmjs.com/package/eslint_d
 [`eslint-loader`]: https://www.npmjs.com/package/eslint-loader
 [`get-tsconfig`]: https://github.com/privatenumber/get-tsconfig
-[`napi-rs`]: https://github.com/napi-rs/napi-rs
 [`tsconfig-paths`]: https://github.com/dividab/tsconfig-paths
 [`typescript`]: https://github.com/microsoft/TypeScript
 [`unrs-resolver`]: https://github.com/unrs/unrs-resolver
diff --git a/docs/rules/extensions.md b/docs/rules/extensions.md
@@ -1,5 +1,7 @@
 # import-x/extensions
 
+🔧💡 This rule is automatically fixable by the [`--fix` CLI option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix) and manually fixable by [editor suggestions](https://eslint.org/docs/latest/use/core-concepts#rule-suggestions).
+
 <!-- end auto-generated rule header -->
 
 Some file resolve algorithms allow you to omit the file extension within the import source path. For example the `node` resolver (which does not yet support ESM/`import`) can resolve `./foo/bar` to the absolute path `/User/someone/foo/bar.js` because the `.js` extension is resolved automatically by default in CJS. Depending on the resolver you can configure more extensions to get resolved automatically.
diff --git a/src/rules/extensions.ts b/src/rules/extensions.ts
@@ -1,5 +1,10 @@
 import path from 'node:path'
 
+import type { JSONSchema4 } from '@typescript-eslint/utils/json-schema'
+import type { RuleFixer } from '@typescript-eslint/utils/ts-eslint'
+import { minimatch } from 'minimatch'
+import type { MinimatchOptions } from 'minimatch'
+
 import type { FileExtension, RuleContext } from '../types.js'
 import {
   isBuiltIn,
@@ -8,32 +13,53 @@ import {
   createRule,
   moduleVisitor,
   resolve,
+  parsePath,
+  stringifyPath,
 } from '../utils/index.js'
 
 const modifierValues = ['always', 'ignorePackages', 'never'] as const
 
 const modifierSchema = {
-  type: 'string' as const,
+  type: 'string',
   enum: [...modifierValues],
-}
+} satisfies JSONSchema4
 
 const modifierByFileExtensionSchema = {
-  type: 'object' as const,
+  type: 'object',
   patternProperties: { '.*': modifierSchema },
-}
+} satisfies JSONSchema4
 
 const properties = {
-  type: 'object' as const,
+  type: 'object',
   properties: {
     pattern: modifierByFileExtensionSchema,
     ignorePackages: {
-      type: 'boolean' as const,
+      type: 'boolean',
     },
     checkTypeImports: {
-      type: 'boolean' as const,
+      type: 'boolean',
+    },
+    pathGroupOverrides: {
+      type: 'array',
+      items: {
+        type: 'object',
+        properties: {
+          pattern: { type: 'string' },
+          patternOptions: { type: 'object' },
+          action: {
+            type: 'string',
+            enum: ['enforce', 'ignore'],
+          },
+        },
+        additionalProperties: false,
+        required: ['pattern', 'action'],
+      },
+    },
+    fix: {
+      type: 'boolean',
     },
   },
-}
+} satisfies JSONSchema4
 
 export type Modifier = (typeof modifierValues)[number]
 
@@ -43,15 +69,27 @@ export interface OptionsItemWithPatternProperty {
   ignorePackages?: boolean
   checkTypeImports?: boolean
   pattern: ModifierByFileExtension
+  pathGroupOverrides?: PathGroupOverride[]
+  fix?: boolean
+}
+
+export interface PathGroupOverride {
+  pattern: string
+  patternOptions?: Record<string, MinimatchOptions>
+  action: 'enforce' | 'ignore'
 }
 
 export interface OptionsItemWithoutPatternProperty {
   ignorePackages?: boolean
   checkTypeImports?: boolean
+  pathGroupOverrides?: PathGroupOverride[]
+  fix?: boolean
 }
 
 export type Options =
   | []
+  | [OptionsItemWithoutPatternProperty]
+  | [OptionsItemWithPatternProperty]
   | [Modifier]
   | [Modifier, OptionsItemWithoutPatternProperty]
   | [Modifier, OptionsItemWithPatternProperty]
@@ -63,16 +101,20 @@ export interface NormalizedOptions {
   pattern?: Record<string, Modifier>
   ignorePackages?: boolean
   checkTypeImports?: boolean
+  pathGroupOverrides?: PathGroupOverride[]
+  fix?: boolean
 }
 
-export type MessageId = 'missing' | 'missingKnown' | 'unexpected'
+export type MessageId = 'missing' | 'missingKnown' | 'unexpected' | 'addMissing'
 
 function buildProperties(context: RuleContext<MessageId, Options>) {
   const result: Required<NormalizedOptions> = {
     defaultConfig: 'never',
     pattern: {},
     ignorePackages: false,
     checkTypeImports: false,
+    pathGroupOverrides: [],
+    fix: false,
   }
 
   for (const obj of context.options) {
@@ -88,16 +130,16 @@ function buildProperties(context: RuleContext<MessageId, Options>) {
 
     // If this is not the new structure, transfer all props to result.pattern
     if (
-      (!('pattern' in obj) || obj.pattern === undefined) &&
-      obj.ignorePackages === undefined &&
-      obj.checkTypeImports === undefined
+      (!('pattern' in obj) || obj.pattern == null) &&
+      obj.ignorePackages == null &&
+      obj.checkTypeImports == null
     ) {
       Object.assign(result.pattern, obj)
       continue
     }
 
     // If pattern is provided, transfer all props
-    if ('pattern' in obj && obj.pattern !== undefined) {
+    if ('pattern' in obj && obj.pattern != null) {
       Object.assign(result.pattern, obj.pattern)
     }
 
@@ -109,6 +151,14 @@ function buildProperties(context: RuleContext<MessageId, Options>) {
     if (typeof obj.checkTypeImports === 'boolean') {
       result.checkTypeImports = obj.checkTypeImports
     }
+
+    if (obj.fix != null) {
+      result.fix = Boolean(obj.fix)
+    }
+
+    if (Array.isArray(obj.pathGroupOverrides)) {
+      result.pathGroupOverrides = obj.pathGroupOverrides
+    }
   }
 
   if (result.defaultConfig === 'ignorePackages') {
@@ -124,14 +174,18 @@ function isExternalRootModule(file: string) {
     return false
   }
   const slashCount = file.split('/').length - 1
+  return slashCount === 0 || (isScoped(file) && slashCount <= 1)
+}
 
-  if (slashCount === 0) {
-    return true
-  }
-  if (isScoped(file) && slashCount <= 1) {
-    return true
+function computeOverrideAction(
+  pathGroupOverrides: PathGroupOverride[],
+  path: string,
+) {
+  for (const { pattern, patternOptions, action } of pathGroupOverrides) {
+    if (minimatch(path, pattern, patternOptions || { nocomment: true })) {
+      return action
+    }
   }
-  return false
 }
 
 export default createRule<Options, MessageId>({
@@ -143,6 +197,8 @@ export default createRule<Options, MessageId>({
       description:
         'Ensure consistent use of file extension within the import path.',
     },
+    fixable: 'code',
+    hasSuggestions: true,
     schema: {
       anyOf: [
         {
@@ -178,6 +234,8 @@ export default createRule<Options, MessageId>({
         'Missing file extension "{{extension}}" for "{{importPath}}"',
       unexpected:
         'Unexpected use of file extension "{{extension}}" for "{{importPath}}"',
+      addMissing:
+        'Add "{{extension}}" file extension from "{{importPath}}" into "{{fixedImportPath}}"',
     },
   },
   defaultOptions: [],
@@ -221,16 +279,29 @@ export default createRule<Options, MessageId>({
 
         const importPathWithQueryString = source.value
 
+        // If not undefined, the user decided if rules are enforced on this import
+        const overrideAction = computeOverrideAction(
+          props.pathGroupOverrides || [],
+          importPathWithQueryString,
+        )
+
+        if (overrideAction === 'ignore') {
+          return
+        }
+
         // don't enforce anything on builtins
-        if (isBuiltIn(importPathWithQueryString, context.settings)) {
+        if (
+          !overrideAction &&
+          isBuiltIn(importPathWithQueryString, context.settings)
+        ) {
           return
         }
 
         const importPath = importPathWithQueryString.replace(/\?(.*)$/, '')
 
         // don't enforce in root external packages as they may have names with `.js`.
         // Like `import Decimal from decimal.js`)
-        if (isExternalRootModule(importPath)) {
+        if (!overrideAction && isExternalRootModule(importPath)) {
           return
         }
 
@@ -261,17 +332,55 @@ export default createRule<Options, MessageId>({
           }
           const extensionRequired = isUseOfExtensionRequired(
             extension,
-            isPackage,
+            !overrideAction && isPackage,
           )
           const extensionForbidden = isUseOfExtensionForbidden(extension)
           if (extensionRequired && !extensionForbidden) {
+            const { pathname, query, hash } = parsePath(
+              importPathWithQueryString,
+            )
+            const fixedImportPath = stringifyPath({
+              pathname: `${
+                /([\\/]|[\\/]?\.?\.)$/.test(pathname)
+                  ? `${
+                      pathname.endsWith('/') ? pathname.slice(0, -1) : pathname
+                    }/index.${extension}`
+                  : `${pathname}.${extension}`
+              }`,
+              query,
+              hash,
+            })
+            const fixOrSuggest = {
+              fix(fixer: RuleFixer) {
+                return fixer.replaceText(
+                  source,
+                  JSON.stringify(fixedImportPath),
+                )
+              },
+            }
             context.report({
               node: source,
               messageId: extension ? 'missingKnown' : 'missing',
               data: {
                 extension,
                 importPath: importPathWithQueryString,
               },
+              ...(extension &&
+                (props.fix
+                  ? fixOrSuggest
+                  : {
+                      suggest: [
+                        {
+                          ...fixOrSuggest,
+                          messageId: 'addMissing',
+                          data: {
+                            extension,
+                            importPath: importPathWithQueryString,
+                            fixedImportPath: fixedImportPath,
+                          },
+                        },
+                      ],
+                    })),
             })
           }
         } else if (
@@ -286,6 +395,14 @@ export default createRule<Options, MessageId>({
               extension,
               importPath: importPathWithQueryString,
             },
+            ...(props.fix && {
+              fix(fixer) {
+                return fixer.replaceText(
+                  source,
+                  JSON.stringify(importPath.slice(0, -(extension.length + 1))),
+                )
+              },
+            }),
           })
         }
       },
diff --git a/src/utils/index.ts b/src/utils/index.ts
@@ -15,6 +15,7 @@ export * from './lazy-value.js'
 export * from './legacy-resolver-settings.js'
 export * from './package-path.js'
 export * from './parse.js'
+export * from './parse-path.js'
 export * from './pkg-dir.js'
 export * from './pkg-up.js'
 export * from './read-pkg-up.js'
diff --git a/src/utils/parse-path.ts b/src/utils/parse-path.ts
@@ -0,0 +1,25 @@
+export interface ParsedPath {
+  pathname: string
+  query: string
+  hash: string
+}
+
+export const parsePath = (path: string): ParsedPath => {
+  const hashIndex = path.indexOf('#')
+  const queryIndex = path.indexOf('?')
+  const hasHash = hashIndex !== -1
+  const hash = hasHash ? path.slice(hashIndex) : ''
+  const hasQuery = queryIndex !== -1 && (!hasHash || queryIndex < hashIndex)
+  const query = hasQuery
+    ? path.slice(queryIndex, hasHash ? hashIndex : undefined)
+    : ''
+  const pathname = hasQuery
+    ? path.slice(0, queryIndex)
+    : hasHash
+      ? path.slice(0, hashIndex)
+      : path
+  return { pathname, query, hash }
+}
+
+export const stringifyPath = ({ pathname, query, hash }: ParsedPath) =>
+  pathname + query + hash
diff --git a/test/rules/extensions.spec.ts b/test/rules/extensions.spec.ts
diff --git a/test/utils/__snapshots__/parse-path.spec.ts.snap b/test/utils/__snapshots__/parse-path.spec.ts.snap
diff --git a/test/utils/parse-path.spec.ts b/test/utils/parse-path.spec.ts

-Original file line number
+Diff line change
@@ @@ -0,0 +1,5 @@ @@
 +---
 +"eslint-plugin-import-x": minor
 +---
++
 +feat(extensions): support `pathGroupOverrides` and `fix` options