fix: try/catch enumerator.iterateFiles gracefully (#360)

JounQin · web-flow · commit 3a3f5f8755f9 · 2025-05-31T08:41:31.000+08:00
diff --git a/.changeset/curvy-swans-ring.md b/.changeset/curvy-swans-ring.md
@@ -0,0 +1,5 @@
+---
+"eslint-plugin-import-x": patch
+---
+
+fix: try/catch `enumerator.iterateFiles` gracefully
diff --git a/.eslintrc.cjs b/.eslintrc.cjs
@@ -1,155 +1,3 @@
 // ! This file is here for testing `no-unused-modules` rule for eslintrc
 
-const { version } = require('eslint/package.json')
-
-const noEslintrc = +version.split('.')[0] > 8
-
-const testCompiled = process.env.TEST_COMPILED === '1'
-
-/** @type {import('eslint').Linter.Config} */
-module.exports = {
-  root: true,
-  reportUnusedDisableDirectives: true,
-  extends: [
-    'eslint:recommended',
-    'plugin:@typescript-eslint/recommended',
-    'plugin:eslint-plugin/recommended',
-    testCompiled && 'plugin:import-x/recommended',
-    'plugin:json/recommended-legacy',
-    'plugin:mdx/recommended',
-    'plugin:n/recommended',
-    !noEslintrc && 'plugin:unicorn/recommended',
-    'plugin:yml/standard',
-    'plugin:yml/prettier',
-    'plugin:prettier/recommended',
-  ].filter(Boolean),
-  env: {
-    node: true,
-    es6: true,
-    es2017: true,
-  },
-  parserOptions: {
-    sourceType: 'module',
-    ecmaVersion: 2020,
-  },
-  rules: {
-    '@typescript-eslint/no-non-null-assertion': 'off',
-    '@typescript-eslint/no-require-imports': 'off',
-
-    'no-constant-condition': noEslintrc ? 'error' : 'off',
-
-    'eslint-plugin/consistent-output': ['error', 'always'],
-    'eslint-plugin/meta-property-ordering': 'error',
-    'eslint-plugin/no-deprecated-context-methods': 'error',
-    'eslint-plugin/no-deprecated-report-api': 'off',
-    'eslint-plugin/prefer-replace-text': 'error',
-    'eslint-plugin/report-message-format': 'error',
-    'eslint-plugin/require-meta-docs-description': [
-      'error',
-      { pattern: String.raw`^(Enforce|Ensure|Prefer|Forbid).+\.$` },
-    ],
-    'eslint-plugin/require-meta-schema': 'error',
-    'eslint-plugin/require-meta-type': 'error',
-    'n/no-extraneous-require': 'off',
-    'n/no-missing-import': 'off',
-    'n/no-missing-require': 'off',
-    'n/no-unsupported-features/es-syntax': 'off',
-    ...(noEslintrc || {
-      'unicorn/filename-case': [
-        'error',
-        {
-          case: 'kebabCase',
-          ignore: [String.raw`^(CONTRIBUTING|README)\.md$`],
-        },
-      ],
-    }),
-    'unicorn/no-array-callback-reference': 'off',
-    'unicorn/no-array-reduce': 'off',
-    'unicorn/no-null': 'off',
-    'unicorn/prefer-module': 'off',
-    'unicorn/prevent-abbreviations': 'off',
-    'unicorn/prefer-at': 'off',
-    'unicorn/prefer-export-from': ['error', { ignoreUsedVariables: true }],
-
-    // dog fooding
-    ...(testCompiled && {
-      'import-x/no-extraneous-dependencies': [
-        'error',
-        {
-          devDependencies: ['test/**'],
-          optionalDependencies: false,
-          peerDependencies: true,
-          bundledDependencies: false,
-        },
-      ],
-      'import-x/unambiguous': 'off',
-    }),
-  },
-
-  overrides: [
-    {
-      files: ['*.ts'],
-      excludedFiles: ['test/fixtures'],
-      rules: {
-        '@typescript-eslint/array-type': [
-          2,
-          {
-            default: 'array-simple',
-          },
-        ],
-        '@typescript-eslint/consistent-type-definitions': ['error', 'type'],
-        '@typescript-eslint/consistent-type-imports': [
-          'error',
-          {
-            fixStyle: 'inline-type-imports',
-          },
-        ],
-        '@typescript-eslint/no-unused-vars': [
-          'error',
-          {
-            argsIgnorePattern: '^_',
-            varsIgnorePattern: '^_',
-          },
-        ],
-        ...(testCompiled && {
-          'import-x/consistent-type-specifier-style': 'error',
-          'import-x/order': [
-            'error',
-            {
-              alphabetize: {
-                order: 'asc',
-              },
-              'newlines-between': 'always',
-            },
-          ],
-        }),
-      },
-      settings: {
-        'import-x/resolver': {
-          typescript: {
-            project: 'tsconfig.base.json',
-          },
-        },
-      },
-    },
-    {
-      files: 'test/**',
-      env: {
-        jest: true,
-      },
-    },
-    {
-      files: 'global.d.ts',
-      rules: {
-        'import-x/no-extraneous-dependencies': 'off',
-      },
-    },
-    {
-      files: 'README.md',
-      rules: {
-        // https://github.com/bmish/eslint-doc-generator/issues/655
-        'no-irregular-whitespace': 'off',
-      },
-    },
-  ],
-}
+module.exports = {}
diff --git a/docs/rules/no-unused-modules.md b/docs/rules/no-unused-modules.md
@@ -9,7 +9,7 @@ Reports:
 - dynamic imports are supported if argument is a literal string
 
 > [!IMPORTANT]
-> This rule is only compatible with legacy configs. If you make use of the new flat config, either do not enable this rule, or provide a legacy eslintrc config at the same time together for this rule to be functional.
+> This rule is only compatible with legacy configs. If you make use of the new flat config, either do not enable this rule, or provide a legacy eslintrc config (even empty) at the same time together for this rule to be functional.
 
 ## Rule Details
 
diff --git a/package.json b/package.json
@@ -119,6 +119,7 @@
     "@types/klaw-sync": "^6.0.5",
     "@types/node": "^22.15.27",
     "@types/pnpapi": "^0.0.5",
+    "@types/tmp": "^0.2.6",
     "@typescript-eslint/eslint-plugin": "^8.33.0",
     "@typescript-eslint/parser": "^8.33.0",
     "@typescript-eslint/rule-tester": "^8.33.0",
@@ -153,6 +154,7 @@
     "redux": "^5.0.1",
     "simple-git-hooks": "^2.13.0",
     "tinyexec": "^1.0.1",
+    "tmp": "^0.2.3",
     "ts-node": "^10.9.2",
     "tsdown": "^0.12.5",
     "type-fest": "^4.41.0",
diff --git a/src/rules/no-unused-modules.ts b/src/rules/no-unused-modules.ts
@@ -23,17 +23,62 @@ import {
 } from '../utils/index.js'
 
 // eslint-disable-next-line import-x/no-named-as-default-member -- incorrect types , commonjs actually
-const { FileEnumerator } = eslintUnsupportedApi
+const { FileEnumerator, shouldUseFlatConfig } = eslintUnsupportedApi
 
-function listFilesToProcess(src: string[], extensions: FileExtension[]) {
-  const enumerator = new FileEnumerator({
-    extensions,
-  })
+function listFilesUsingFileEnumerator(
+  src: string[],
+  extensions: FileExtension[],
+) {
+  // We need to know whether this is being run with flat config in order to
+  // determine how to report errors if FileEnumerator throws due to a lack of eslintrc.
+
+  const { ESLINT_USE_FLAT_CONFIG } = process.env
+
+  // This condition is sufficient to test in v8, since the environment variable is necessary to turn on flat config
+  let isUsingFlatConfig: boolean
+
+  // In the case of using v9, we can check the `shouldUseFlatConfig` function
+  // If this function is present, then we assume it's v9
+  try {
+    isUsingFlatConfig =
+      // @ts-expect-error -- only available in ESLint v9
+      shouldUseFlatConfig && ESLINT_USE_FLAT_CONFIG !== 'false'
+  } catch {
+    // We don't want to throw here, since we only want to init the
+    // boolean if the function is available.
+    isUsingFlatConfig =
+      !!ESLINT_USE_FLAT_CONFIG && ESLINT_USE_FLAT_CONFIG !== 'false'
+  }
+
+  const enumerator = new FileEnumerator({ extensions })
 
-  return Array.from(enumerator.iterateFiles(src), ({ filePath, ignored }) => ({
-    ignored,
-    filename: filePath,
-  }))
+  try {
+    return Array.from(
+      enumerator.iterateFiles(src),
+      ({ filePath, ignored }) => ({ filename: filePath, ignored }),
+    )
+  } catch (error) {
+    // If we're using flat config, and FileEnumerator throws due to a lack of eslintrc,
+    // then we want to throw an error so that the user knows about this rule's reliance on
+    // the legacy config.
+    if (
+      isUsingFlatConfig &&
+      (error as Error).message.includes('No ESLint configuration found')
+    ) {
+      throw new Error(`
+Due to the exclusion of certain internal ESLint APIs when using flat config,
+the import-x/no-unused-modules rule requires an .eslintrc file (even empty) to know which
+files to ignore (even when using flat config).
+The .eslintrc file only needs to contain "ignorePatterns", or can be empty if
+you do not want to ignore any files.
+
+See https://github.com/import-js/eslint-plugin-import/issues/3079
+for additional context.
+`)
+    }
+    // If this isn't the case, then we'll just let the error bubble up
+    throw error
+  }
 }
 
 const DEFAULT = 'default'
@@ -141,10 +186,13 @@ const resolveFiles = (
 ) => {
   const extensions = [...getFileExtensions(context.settings)]
 
-  const srcFileList = listFilesToProcess(src, extensions)
+  const srcFileList = listFilesUsingFileEnumerator(src, extensions)
 
   // prepare list of ignored files
-  const ignoredFilesList = listFilesToProcess(ignoreExports, extensions)
+  const ignoredFilesList = listFilesUsingFileEnumerator(
+    ignoreExports,
+    extensions,
+  )
   for (const { filename } of ignoredFilesList) ignoredFiles.add(filename)
 
   // prepare list of source files, don't consider files from node_modules
diff --git a/test/fixtures/eslint-v9/.gitignore b/test/fixtures/eslint-v9/.gitignore
@@ -0,0 +1 @@
+node_modules
diff --git a/test/fixtures/eslint-v9/.npmrc b/test/fixtures/eslint-v9/.npmrc
@@ -0,0 +1 @@
+package-lock=false
diff --git a/test/fixtures/eslint-v9/eslint.config.mjs b/test/fixtures/eslint-v9/eslint.config.mjs
@@ -0,0 +1,22 @@
+import { importX } from 'eslint-plugin-import-x'
+import js from '@eslint/js'
+
+export default [
+  js.configs.recommended,
+  importX.flatConfigs.recommended,
+  {
+    files: ['**/*.{js,mjs,cjs}'],
+    languageOptions: {
+      ecmaVersion: 'latest',
+      sourceType: 'module',
+    },
+    ignores: ['eslint.config.mjs', 'node_modules/*'],
+    rules: {
+      'no-unused-vars': 'off',
+      'import-x/no-dynamic-require': 'warn',
+      'import-x/no-nodejs-modules': 'warn',
+      'import-x/no-unused-modules': ['warn', { unusedExports: true }],
+      'import-x/no-cycle': 'warn',
+    },
+  },
+]
diff --git a/test/fixtures/eslint-v9/package.json b/test/fixtures/eslint-v9/package.json
@@ -0,0 +1,14 @@
+{
+  "name": "eslint-v9",
+  "version": "1.0.0",
+  "type": "module",
+  "main": "index.js",
+  "scripts": {
+    "lint": "eslint src --report-unused-disable-directives"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.17.0",
+    "eslint": "^9.17.0",
+    "eslint-plugin-import-x": "file:../../.."
+  }
+}
diff --git a/test/fixtures/eslint-v9/src/depth-zero.js b/test/fixtures/eslint-v9/src/depth-zero.js
@@ -0,0 +1,3 @@
+import { foo } from './es6/depth-one-dynamic'
+
+foo()
diff --git a/test/fixtures/eslint-v9/src/exports.js b/test/fixtures/eslint-v9/src/exports.js
@@ -0,0 +1,6 @@
+//import c from './exports';
+import { a, b } from './exports'
+
+import path from 'path'
+import fs from 'node:fs'
+import console from 'console'
diff --git a/test/rules/no-unused-modules.spec.ts b/test/rules/no-unused-modules.spec.ts
@@ -1,3 +1,5 @@
+import { execSync } from 'node:child_process'
+import type { ChildProcess } from 'node:child_process'
 import fs from 'node:fs'
 
 import { jest } from '@jest/globals'
@@ -7,8 +9,14 @@ import type { TSESLint } from '@typescript-eslint/utils'
 // eslint-disable-next-line import-x/default -- incorrect types
 import eslint8UnsupportedApi from 'eslint8.56/use-at-your-own-risk'
 import { RuleTester as ESLint9_FlatRuleTester } from 'eslint9'
+import { dirSync } from 'tmp'
 
-import { createRuleTestCaseFunctions, testFilePath, parsers } from '../utils.js'
+import {
+  createRuleTestCaseFunctions,
+  testFilePath,
+  parsers,
+  isESLint9,
+} from '../utils.js'
 import type { GetRuleModuleOptions, GetRuleModuleMessageIds } from '../utils.js'
 
 import { cjsRequire as require } from 'eslint-plugin-import-x'
@@ -1560,3 +1568,40 @@ for (const [name, FlatRuleTester] of [
     })
   })
 }
+
+;(isESLint9 ? describe : describe.skip)('with eslint 9+', () => {
+  it('provides meaningful error when eslintrc is not present', () => {
+    // Create temp directory outside of project root
+    const { name: tempDir, removeCallback } = dirSync({
+      unsafeCleanup: true,
+    })
+
+    // Copy example project to temp directory
+    // eslint-disable-next-line n/no-unsupported-features/node-builtins -- false positive
+    fs.cpSync(testFilePath('eslint-v9'), tempDir, {
+      recursive: true,
+    })
+
+    let errorMessage = ''
+
+    // We run `test-compiled` first, so that the plugin is already built
+    // But don't forget to run `yarn build` first if you're developing the rule or test case
+
+    // Install the plugin and run the lint command in the temp directory
+    try {
+      execSync(`npm install -D ${process.cwd()} && npm run lint`, {
+        cwd: tempDir,
+      })
+    } catch (error) {
+      errorMessage = (error as ChildProcess).stderr!.toString()
+    }
+
+    // Verify that the error message is as expected
+    expect(errorMessage).toContain(
+      'the import-x/no-unused-modules rule requires an .eslintrc file (even empty)',
+    )
+
+    // Cleanup
+    removeCallback()
+  }, 100_000)
+})
diff --git a/test/utils.ts b/test/utils.ts
diff --git a/yarn.lock b/yarn.lock

-Original file line number
+Diff line change
@@ @@ -0,0 +1,5 @@ @@
 +---
 +"eslint-plugin-import-x": patch
 +---
++
 +fix: try/catch `enumerator.iterateFiles` gracefully
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+import { foo } from './es6/depth-one-dynamic'`
	`2`	`+`
	`3`	`+foo()`