[Fix] no-unused-modules: only honor flat config ignores on ESLint 8.21+, and support older config-array (isIgnored) APIs

Flat config does not exist before ESLint 8.21, so a discovered
`eslint.config.js` is inert on older versions and its `ignores` must not filter the file set.
Gate the predicate on the installed ESLint version, and additionally guard the `config-array` API so ESLint 8.21-8.27
(`isIgnored`, no `isFileIgnored`/`isDirectoryIgnored`) works,
rather than crashing with `configArray.normalizeSync is not a function`
(ESLint 7, `config-array` 0.5.0)
or a spurious "neither could be loaded" throw (ESLint 2-6).

Author: ljharb

src/core/flatConfigIgnores.js

@@ -1,5 +1,6 @@
 import fs from 'fs';
 import { dirname, join, resolve } from 'path';
+import semver from 'semver';
 
 // the sync-loadable subset of ESLint's flat config filenames, in its lookup priority order.
 // `.ts`/`.mts`/`.cts` are intentionally omitted: they require a loader and cannot be `require`d.
@@ -74,20 +75,47 @@ function resolveConfigArray(name) {
   }
 }
 
+// Flat config only exists as of ESLint 8.21 (`FlatESLint` and the `ESLINT_USE_FLAT_CONFIG` opt-in):
+// older versions never read `eslint.config.js`, so a discovered one is inert there and filtering by
+// its `ignores` would drop files that ESLint itself would lint.
+function supportsFlatConfig() {
+  try {
+    // eslint-disable-next-line global-require
+    return semver.gte(require('eslint/package.json').version, '8.21.0');
+  } catch (eslintResolveError) {
+    // `eslint` itself is not resolvable: assume a modern, flat-config-capable install.
+    return true;
+  }
+}
+
+// The minimum usable config-array API: `normalizeSync` plus a per-file ignore check - `isFileIgnored`
+// since v0.11 (and in every `@eslint/config-array`), or its earlier spelling `isIgnored` in v0.9–v0.10
+// (shipped with ESLint 8.21–8.27). ESLint 7.32 ships v0.5, which predates all of these.
+function isUsableConfigArray(ConfigArray) {
+  return typeof ConfigArray === 'function'
+    && typeof ConfigArray.prototype.normalizeSync === 'function'
+    && (typeof ConfigArray.prototype.isFileIgnored === 'function' || typeof ConfigArray.prototype.isIgnored === 'function');
+}
+
+function tryResolveConfigArray(name) {
+  try {
+    const ConfigArray = resolveConfigArray(name);
+    return isUsableConfigArray(ConfigArray) ? ConfigArray : null;
+  } catch (resolveError) {
+    return null;
+  }
+}
+
 // ESLint 9.4+/10 ship the flat config engine as `@eslint/config-array`; ESLint 8 and 9.0–9.3 ship the
 // same API under its pre-fork name `@humanwhocodes/config-array`. Resolved lazily (only on this
 // flat-config fallback path). If we are honoring flat config but neither resolves, that is a broken
-// install — throw rather than silently scan ignored files.
+// install - throw rather than silently scan ignored files.
 function getConfigArray() {
-  try {
-    return resolveConfigArray('@eslint/config-array');
-  } catch (eslintConfigArrayError) {
-    try {
-      return resolveConfigArray('@humanwhocodes/config-array');
-    } catch (humanwhocodesConfigArrayError) {
-      throw new Error('eslint-plugin-import: honoring flat config `ignores` in `no-unused-modules` requires `@eslint/config-array` (ESLint 9.4+) or `@humanwhocodes/config-array` (ESLint 8–9.3); neither could be loaded.');
-    }
+  const ConfigArray = tryResolveConfigArray('@eslint/config-array') || tryResolveConfigArray('@humanwhocodes/config-array');
+  if (!ConfigArray) {
+    throw new Error('eslint-plugin-import: honoring flat config `ignores` in `no-unused-modules` requires `@eslint/config-array` (ESLint 9.4+) or `@humanwhocodes/config-array` (ESLint 8–9.3); neither could be loaded.');
   }
+  return ConfigArray;
 }
 
 /**
@@ -96,9 +124,14 @@ function getConfigArray() {
  * @param {string} cwd - directory to resolve the flat config from
  * @returns {{ isFileIgnored: (p: string) => boolean, isDirectoryIgnored: (p: string) => boolean } | null}
  *   a predicate over absolute paths, or `null` when no flat config / global ignores apply.
- * @throws if a flat config with global `ignores` is present but no config-array implementation resolves.
+ * @throws if, on a flat-config-capable ESLint, a flat config with global `ignores` is present but no
+ *   usable config-array implementation resolves.
  */
 function buildPredicate(cwd) {
+  if (!supportsFlatConfig()) {
+    return null;
+  }
+
   const configPath = findConfigFile(cwd);
   if (!configPath) {
     return null;
@@ -126,8 +159,14 @@ function buildPredicate(cwd) {
   const configArray = new ConfigArray(configs, { basePath: dirname(configPath), schema: {} });
   configArray.normalizeSync();
   return {
-    isFileIgnored: (absolutePath) => configArray.isFileIgnored(absolutePath),
-    isDirectoryIgnored: (absolutePath) => configArray.isDirectoryIgnored(absolutePath),
+    isFileIgnored: typeof configArray.isFileIgnored === 'function'
+      ? (absolutePath) => configArray.isFileIgnored(absolutePath)
+      : (absolutePath) => configArray.isIgnored(absolutePath),
+    // config-array < v0.11 has no `isDirectoryIgnored`; it only prunes the walk, so files under an
+    // ignored directory are still filtered one-by-one by `isFileIgnored` above.
+    isDirectoryIgnored: typeof configArray.isDirectoryIgnored === 'function'
+      ? (absolutePath) => configArray.isDirectoryIgnored(absolutePath)
+      : () => false,
   };
 }
 

tests/src/core/listFilesWithNodeFs.js

@@ -3,7 +3,7 @@ import path from 'path';
 import mockProperty from 'mock-property';
 
 import listFilesWithNodeFs from 'core/listFilesWithNodeFs';
-import { getFilename } from '../utils';
+import { eslintVersionSatisfies, getFilename } from '../utils';
 
 // Fixture layout under tests/files/listFilesWithNodeFs/:
 //   README.md   top.js   top.ts
@@ -105,9 +105,23 @@ describe('listFilesWithNodeFs, flat-config ignores', function () {
   const igRoot = getFilename('listFilesWithNodeFs-flatignores');
   const g = (...segments) => path.join(igRoot, ...segments);
 
-  it('honors the flat config global `ignores` resolved from cwd', function () {
+  // flat config only exists as of ESLint 8.21: older versions never read `eslint.config.js`,
+  // so a discovered one is inert there and nothing may be filtered by it
+  const supportsFlatConfig = eslintVersionSatisfies('>= 8.21');
+
+  (supportsFlatConfig ? it : it.skip)('honors the flat config global `ignores` resolved from cwd', function () {
+    expect(listFilesWithNodeFs([igRoot], ['.js'], igRoot).sort()).to.deep.equal([
+      g('eslint.config.js'),
+      g('keep.js'),
+      g('src', 'a.js'),
+    ]);
+  });
+
+  (supportsFlatConfig ? it.skip : it)('ignores `eslint.config.js` entirely on an ESLint without flat config support', function () {
     expect(listFilesWithNodeFs([igRoot], ['.js'], igRoot).sort()).to.deep.equal([
       g('eslint.config.js'),
+      g('ignored-dir', 'nested.js'),
+      g('ignored-file.js'),
       g('keep.js'),
       g('src', 'a.js'),
     ]);
@@ -124,7 +138,7 @@ describe('listFilesWithNodeFs, flat-config ignores', function () {
     ]);
   });
 
-  it('throws, rather than silently scanning ignored files, when a flat config has global `ignores` but no config-array implementation resolves', function () {
+  (supportsFlatConfig ? it : it.skip)('throws, rather than silently scanning ignored files, when a flat config has global `ignores` but no config-array implementation resolves', function () {
     // stub every installed config-array copy (resolved both directly and from eslint's dir, as the
     // code does) so accessing `ConfigArray` throws; copies that aren't installed already throw.
     const eslintDir = path.dirname(require.resolve('eslint/package.json'));