NEW(eslint): @W-18495555@: Allow users to supply their own custom "flat" ESLint configuration file (#302)

Author: stephen-carter-at-sf

packages/code-analyzer-eslint-engine/package.json

@@ -33,10 +33,12 @@
   },
   "devDependencies": {
     "@types/jest": "^29.5.14",
+    "@types/unzipper": "^0.10.11",
     "cross-env": "^7.0.3",
     "jest": "^29.7.0",
     "rimraf": "^6.0.01",
-    "ts-jest": "^29.3.3"
+    "ts-jest": "^29.3.3",
+    "unzipper": "^0.12.3"
   },
   "engines": {
     "node": ">=20.0.0"

packages/code-analyzer-eslint-engine/src/config.ts

@@ -109,8 +109,9 @@ export const ESLINT_ENGINE_CONFIG_DESCRIPTION: ConfigDescription = {
 
 // See https://eslint.org/docs/latest/use/configure/configuration-files
 // We currently do not support Typescript config files are since they require additional setup
-export const FLAT_ESLINT_CONFIG_FILES: string[] =
-    ['eslint.config.js', 'eslint.config.mjs', 'eslint.config.cjs'];
+export const DISCOVERABLE_FLAT_ESLINT_CONFIG_FILES: string[] =
+    ['eslint.config.js', 'eslint.config.cjs', 'eslint.config.mjs'];
+export const FLAT_ESLINT_CONFIG_FILE_EXTS: string[] = ['.js', '.cjs', '.mjs'];
 
 // See https://eslint.org/docs/v8.x/use/configure/configuration-files#configuration-file-formats
 export const LEGACY_ESLINT_CONFIG_FILES: string[] =
@@ -148,9 +149,11 @@ class ESLintEngineConfigValueExtractor {
     extractESLintConfigFileValue(): string | undefined {
         const eslintConfigFileField: string = 'eslint_config_file';
         const eslintConfigFile: string | undefined = this.delegateExtractor.extractFile(eslintConfigFileField, DEFAULT_CONFIG.eslint_config_file);
-        if (eslintConfigFile && !LEGACY_ESLINT_CONFIG_FILES.includes(path.basename(eslintConfigFile))) {
-            throw new Error(getMessage('InvalidLegacyConfigFileName', this.delegateExtractor.getFieldPath(eslintConfigFileField),
-                path.basename(eslintConfigFile), JSON.stringify(LEGACY_ESLINT_CONFIG_FILES)));
+        if (eslintConfigFile && !(isValidLegacyConfigFileName(eslintConfigFile) || isValidFlatConfigFileName(eslintConfigFile))) {
+            throw new Error(getMessage('InvalidESLintConfigFileName',
+                this.delegateExtractor.getFieldPath(eslintConfigFileField),
+                JSON.stringify(FLAT_ESLINT_CONFIG_FILE_EXTS),
+                JSON.stringify(LEGACY_ESLINT_CONFIG_FILES)));
         }
         return eslintConfigFile;
     }
@@ -198,3 +201,12 @@ class ESLintEngineConfigValueExtractor {
         return this.delegateExtractor.extractBoolean(field_name, DEFAULT_CONFIG[field_name as keyof ESLintEngineConfig] as boolean)!;
     }
 }
+
+function isValidLegacyConfigFileName(eslintConfigFile: string): boolean {
+    // For legacy config files, we only allow specific file names so we are confident it is a legacy config file.
+    return LEGACY_ESLINT_CONFIG_FILES.includes(path.basename(eslintConfigFile).toLowerCase());
+}
+
+function isValidFlatConfigFileName(eslintConfigFile: string): boolean {
+    return FLAT_ESLINT_CONFIG_FILE_EXTS.includes(path.extname(eslintConfigFile).toLowerCase());
+}

packages/code-analyzer-eslint-engine/src/engine.ts

@@ -60,14 +60,21 @@ export class ESLintEngine extends Engine {
         const userConfigInfo: UserConfigInfo = this.getUserConfigInfo(describeOptions.workspace);
         this.emitLogEvent(LogLevel.Fine, `Detected the following state regarding the user's ESLint configuration: ${userConfigInfo}`);
 
-        if (this.shouldDelegateToV8(userConfigInfo)) {
+        if (userConfigInfo.getState() === UserConfigState.LEGACY_USER_CONFIG) {
+            this.emitLogEvent(LogLevel.Warn, getMessage('DetectedLegacyConfig',
+                userConfigInfo.getChosenUserConfigFile() ?? userConfigInfo.getChosenUserIgnoreFile()!));
             return this.delegateV8Engine.describeRules(describeOptions);
-        } else if (userConfigInfo.getUserIgnoreFile()) {
-            this.emitLogEvent(LogLevel.Warn, getMessage('IgnoringLegacyIgnoreFile', userConfigInfo.getUserIgnoreFile()!));
         }
 
-        if (userConfigInfo.getUserConfigFile()) { // TODO: Remove this as soon as we allow user's to supply their own flat config file.
-            this.emitLogEvent(LogLevel.Warn, getMessage('IgnoringFlatConfigFile', userConfigInfo.getUserConfigFile()!));
+        if (userConfigInfo.getChosenUserConfigFile()) {
+            this.emitLogEvent(LogLevel.Debug, getMessage('ApplyingFlatConfigFile', userConfigInfo.getChosenUserConfigFile()!));
+        } else if (userConfigInfo.getDiscoveredConfigFile()) {
+            this.emitLogEvent(LogLevel.Info, getMessage('UnusedESLintConfigFile',
+                makeRelativeTo(process.cwd(), userConfigInfo.getDiscoveredConfigFile()!),
+                makeRelativeTo(this.engineConfig.config_root, userConfigInfo.getDiscoveredConfigFile()!)));
+        }
+        if (userConfigInfo.getChosenUserIgnoreFile()) {
+            this.emitLogEvent(LogLevel.Warn, getMessage('IgnoringLegacyIgnoreFile', userConfigInfo.getChosenUserIgnoreFile()!));
         }
 
         this.emitDescribeRulesProgressEvent(10);
@@ -97,7 +104,7 @@ export class ESLintEngine extends Engine {
     async runRules(ruleNames: string[], runOptions: RunOptions): Promise<EngineRunResults> {
         this.emitRunRulesProgressEvent(0);
         const userConfigInfo: UserConfigInfo = this.getUserConfigInfo(runOptions.workspace);
-        if (this.shouldDelegateToV8(userConfigInfo)) {
+        if (userConfigInfo.getState() === UserConfigState.LEGACY_USER_CONFIG) {
             return this.delegateV8Engine.runRules(ruleNames, runOptions);
         }
 
@@ -161,17 +168,14 @@ export class ESLintEngine extends Engine {
         return this.userConfigInfoCache.get(cacheKey)!;
     }
 
-    private shouldDelegateToV8(userConfigInfo: UserConfigInfo): boolean {
-        return userConfigInfo.getState() === UserConfigState.LEGACY_USER_CONFIG;
-    }
-
     private async getESLintContext(workspace?: Workspace): Promise<ESLintContext> {
         const cacheKey: string = workspace?.getWorkspaceId() ?? process.cwd();
         if (!this.eslintContextCache.has(cacheKey)) {
             const userConfigInfo: UserConfigInfo = this.getUserConfigInfo(workspace);
             const eslintWorkspace: ESLintWorkspace = ESLintWorkspace.from(workspace,
-                this.engineConfig.config_root, this.engineConfig.file_extensions, userConfigInfo.getUserConfigFile());
-            const context: ESLintContext = await calculateESLintContext(this.engineConfig, eslintWorkspace);
+                this.engineConfig.config_root, this.engineConfig.file_extensions, userConfigInfo.getChosenUserConfigFile());
+            const context: ESLintContext = await calculateESLintContext(this.engineConfig, eslintWorkspace,
+                userConfigInfo.getChosenUserConfigFile());
             this.eslintContextCache.set(cacheKey, context);
         }
         return this.eslintContextCache.get(cacheKey)!;
@@ -267,3 +271,11 @@ function normalizeEndValue(endValue: number | undefined): number | undefined {
     /* istanbul ignore next */
     return endValue && endValue > 0 ? endValue : undefined;
 }
+
+
+function makeRelativeTo(absFolderPath: string, absFilePath: string): string {
+    absFolderPath = absFolderPath.endsWith(path.sep) ?
+        /* istanbul ignore next */ absFolderPath : absFolderPath + path.sep;
+    return absFilePath.startsWith(absFolderPath) ?
+        absFilePath.slice(absFolderPath.length) : /* istanbul ignore next */  absFilePath;
+}

packages/code-analyzer-eslint-engine/src/eslint-context.ts

@@ -13,6 +13,7 @@ export enum ESLintRuleStatus {
 
 export type ESLintContext = {
     baseDirectory: string,
+    userConfigFile?: string,
     filesToScan: string[],
     ruleInfo: {
         [ruleName: string]: {
@@ -22,12 +23,13 @@ export type ESLintContext = {
     }
 }
 
-export async function calculateESLintContext(engineConfig: ESLintEngineConfig, eslintWorkspace: ESLintWorkspace): Promise<ESLintContext> {
+export async function calculateESLintContext(engineConfig: ESLintEngineConfig, eslintWorkspace: ESLintWorkspace, userConfigFile?: string): Promise<ESLintContext> {
     const baseDirectory: string = await eslintWorkspace.getBaseDirectory();
-    const eslint: ESLint = createESLint(engineConfig, baseDirectory);
+    const eslint: ESLint = createESLint(engineConfig, baseDirectory, userConfigFile);
 
     const context: ESLintContext = {
         baseDirectory: baseDirectory,
+        userConfigFile: userConfigFile,
         filesToScan: await eslintWorkspace.getFilesToScan(eslint),
         ruleInfo: {}
     }
@@ -80,7 +82,9 @@ function getRuleStatusFromRuleEntry(ruleEntry: Linter.RuleEntry): ESLintRuleStat
     if (typeof ruleEntry === "number") {
         return ruleEntry === 2 ? ESLintRuleStatus.ERROR :
             ruleEntry === 1 ? ESLintRuleStatus.WARN : ESLintRuleStatus.OFF;
-    } else if (typeof ruleEntry === "string") {
+    } else /* istanbul ignore if */ if (typeof ruleEntry === "string") {
+        // I believe ESLint 9 normalizes the ruleEntry to always be numbers when we invoke calculateConfigForFile
+        // but just in case things change, we should keep this branch of code that handles the string case for safety.
         return ruleEntry.toLowerCase() === "error" ? ESLintRuleStatus.ERROR :
             ruleEntry.toLowerCase() === "warn" ? ESLintRuleStatus.WARN : ESLintRuleStatus.OFF;
     }

packages/code-analyzer-eslint-engine/src/eslint-wrapper.ts

@@ -6,13 +6,13 @@ import {makeStringifiable} from "./utils";
 import { indent } from "@salesforce/code-analyzer-engine-api/utils";
 
 
-export function createESLint(engineConfig: ESLintEngineConfig, baseDirectory: string, rulesToRun?: Set<string>): ESLintWrapper {
+export function createESLint(engineConfig: ESLintEngineConfig, baseDirectory: string, userConfigFile?: string, rulesToRun?: Set<string>): ESLintWrapper {
     const baseConfigFactory: BaseConfigFactory = new BaseConfigFactory(engineConfig);
     const eslintOptions: ESLint.Options = {
         cwd: baseDirectory,                      // The base working directory. This must be an absolute path.
         errorOnUnmatchedPattern: false,          // Unless set to false, the eslint.lintFiles() method will throw an error when no target files are found.
         baseConfig: baseConfigFactory.createBaseConfigArray(),
-        overrideConfigFile: true,  //TODO: Will Add in Users Config File
+        overrideConfigFile: userConfigFile ?? true,  // Oddly enough ESLint documents that "true" means don't go auto looking for a config file (which we set if we didn't find one ourselves)
     };
     if (rulesToRun) {
         // Using a ruleFilter ensures that we only run the rules that the user has selected. This approach is much
@@ -31,7 +31,7 @@ export class ESLintWrapper extends ESLint {
         try {
             super(options);
             this._options = options;
-        } catch (error) {
+        } catch (error) /* istanbul ignore next */ {
             throw wrapESLintError(error, 'ESLint', options);
         }
     }
@@ -41,7 +41,7 @@ export class ESLintWrapper extends ESLint {
         try {
             return await super.calculateConfigForFile(filePath);
         } catch (error) {
-            throw wrapESLintError(error, `ESLint.calculateConfigForFile(${filePath})`, this._options);
+            throw await wrapESLintError(error, `ESLint.calculateConfigForFile("${filePath}")`, this._options);
         }
 
     }
@@ -50,20 +50,41 @@ export class ESLintWrapper extends ESLint {
         try {
             return await super.isPathIgnored(filePath);
         } catch (error) { /* istanbul ignore next */
-            throw wrapESLintError(error, `ESLint.isPathIgnored(${filePath})`, this._options);
+            throw await wrapESLintError(error, `ESLint.isPathIgnored("${filePath}")`, this._options);
         }
     }
 }
 
+class WrappedError extends Error {}
+
+async function wrapESLintError(rawError: unknown, fcnCallStr: string, options: ESLint.Options): Promise<Error> {
+    if (rawError instanceof WrappedError) {
+        return rawError; // Prevent wrapping multiple times
+    }
+
+    // Before throwing the actual error message, we first want to validate the user's config file in an isolated
+    // environment see if it is even valid when run by itself without any other configurations.
+    // If not, then we display the simpler error and options.
+    if (typeof options.overrideConfigFile === "string") {
+        const simpleOptions: ESLint.Options = {overrideConfigFile: options.overrideConfigFile};
+        try {
+            const rawESLint: ESLint = new ESLint(simpleOptions);
+            await rawESLint.calculateConfigForFile('dummy.js');
+        } catch (err) {
+            rawError = err;
+            fcnCallStr = 'ESLint.calculateConfigForFile';
+            options = simpleOptions;
+        }
+    }
 
-function wrapESLintError(rawError: unknown, fcnCallStr: string, options: ESLint.Options): Error {
-    const rawErrMsg: string = rawError instanceof Error ? rawError.message : /* istanbul ignore next */
-        String(rawError);
-    const eslintOptionsStr: string = indent(stringifyESLintOptions(options), '    |');
-    const wrappedErrMsg: string = rawErrMsg.includes('conflict') ? // TODO: See if this conflict case ever happens anymore
+    /* istanbul ignore next */
+    const rawErrMsg: string = indent(rawError instanceof Error ?
+        rawError.stack ?? rawError.message : String(rawError), '  | ');
+    const eslintOptionsStr: string = indent(stringifyESLintOptions(options), '    ');
+    const wrappedErrMsg: string = rawErrMsg.includes('Cannot redefine plugin') ? // TODO: Maybe with W-18695515 we can manually resolve conflicts
         getMessage('ESLintThrewExceptionWithPluginConflictMessage', fcnCallStr, rawErrMsg, eslintOptionsStr)
         : getMessage('ESLintThrewExceptionWithUnknownMessage', fcnCallStr, rawErrMsg, eslintOptionsStr);
-    return new Error(wrappedErrMsg, {cause: rawError});
+    return new WrappedError(wrappedErrMsg, {cause: rawError});
 }
 
 

packages/code-analyzer-eslint-engine/src/messages.ts

@@ -23,7 +23,7 @@ const MESSAGE_CATALOG : { [key: string]: string } = {
     ConfigFieldDescription_disable_javascript_base_config:
         `Whether to turn off the default base configuration that supplies the standard ESLint rules for JavaScript files.\n` +
         `The base configuration for JavaScript files adds the rules from the "eslint:all" configuration to Code Analyzer.\n` +
-        `See https://eslint.org/docs/v8.x/rules for the list of rules.`, // TODO: This link will change when we move to v9
+        `See https://eslint.org/docs/latest/rules for the list of rules.`,
 
     ConfigFieldDescription_disable_lwc_base_config:
         `Whether to turn off the default base configuration that supplies the LWC rules for JavaScript files.\n` +
@@ -34,7 +34,7 @@ const MESSAGE_CATALOG : { [key: string]: string } = {
     ConfigFieldDescription_disable_typescript_base_config:
         `Whether to turn off the default base configuration that supplies the standard rules for TypeScript files\n` +
         `The base configuration for TypeScript files adds the rules from the "plugin:@typescript-eslint:all" configuration to Code Analyzer.\n` +
-        `See https://typescript-eslint.io/rules and https://eslint.org/docs/v8.x/rules for the lists of rules.`, // TODO: This link will change when we move to v9
+        `See https://typescript-eslint.io/rules and https://eslint.org/docs/latest/rules for the lists of rules.`,
 
     ConfigFieldDescription_file_extensions:
         `Extensions of the files in your workspace that will be used to discover rules.\n` +
@@ -47,8 +47,8 @@ const MESSAGE_CATALOG : { [key: string]: string } = {
     UnsupportedEngineName:
         `The ESLintEnginePlugin does not support an engine with name '%s'.`,
 
-    InvalidLegacyConfigFileName:
-        `The '%s' configuration value is invalid. Expected the file name '%s' to be one of the following: %s`,
+    InvalidESLintConfigFileName:
+        `The '%s' configuration value is invalid. Expected either a "flat" ESLint configuration file that ends with %s or a known "legacy" ESLint configuration file name from among %s.`,
 
     InvalidLegacyIgnoreFileName:
         `The '%s' configuration value is invalid. Expected the file name '%s' to be equal to '%s'.`,
@@ -62,7 +62,7 @@ const MESSAGE_CATALOG : { [key: string]: string } = {
     ESLintWarnedWhenScanningFile:
         `When scanning file '%s' with the eslint engine, ESLint gave the following warning:\n%s`,
 
-    ESLintThrewExceptionWithPluginConflictMessage:
+    ESLintThrewExceptionWithPluginConflictMessage: // TODO: Hopefully with W-18695515 we can manually resolve conflicts and we won't need this
         `The eslint engine encountered a conflict between a plugin supplied by one of your ESLint configuration ` +
         `files and a plugin supplied by the base configuration.\n` +
         `To continue to use your custom config you may need to disable one or more of the provided base ` +
@@ -79,34 +79,32 @@ const MESSAGE_CATALOG : { [key: string]: string } = {
         `    eslint:\n` +
         `      eslint_config_file: null\n` +
         `      auto_discover_eslint_config: false\n\n` +
-        `Error thrown from %s': %s\n\n` +
+        `Error thrown from %s':\n%s\n\n` +
         'ESLint options used:\n%s',
 
     ESLintThrewExceptionWithUnknownMessage:
-        `The eslint engine encountered an unexpected error thrown from '%s': %s\n\n` +
+        `The eslint engine encountered an unexpected error thrown from '%s':\n%s\n\n` +
         'ESLint options used:\n%s',
 
-    UnusedEslintConfigFile:
+    UnusedESLintConfigFile:
         `The ESLint configuration file '%s' was found but not applied.\n` +
         `To apply this configuration file, set it as the eslint_config_file value in your Code Analyzer configuration. For example:\n` +
         `  engines:\n` +
         `    eslint:\n` +
         `      eslint_config_file: "%s"\n` +
-        `Alternatively, to have Code Analyzer automatically discover and apply any ESLint configuration and ignore files found in your workspace, set the auto_discover_eslint_config value to true.`,
-
-    UnusedEslintIgnoreFile:
-        `The ESLint ignore file '%s' was found but not applied.\n` +
-        `To apply this ignore file, set it as the eslint_ignore_file value in your Code Analyzer configuration. For example:\n` +
-        `  engines:\n` +
-        `    eslint:\n` +
-        `      eslint_ignore_file: "%s"\n` +
-        `Alternatively, to have Code Analyzer automatically discover and apply any ESLint configuration and ignore files found in your workspace, set the auto_discover_eslint_config value to true.`,
+        `Alternatively, to have Code Analyzer attempt to automatically discover your ESLint configuration file in your workspace, set the auto_discover_eslint_config value to true.`,
 
     IgnoringLegacyIgnoreFile:
         `Ignoring '%s' since ESLint v9+ does not support legacy ignore files.`,
 
-    IgnoringFlatConfigFile: // TODO: Remove this as soon as we support user's providing their own flat config files
-        `Ignoring '%s' since ESLint "Flat" configuration files are not yet supported by this version of the 'eslint' engine.`,
+    DetectedLegacyConfig:
+        `Using ESLint v8 instead of ESLint v9 since the use of a "legacy" ESLint configuration file or ignore file was detected: %s.\n` +
+        `Since ESLint v8 is no longer supported, Code Analyzer will be removing support for "legacy" ESLint configuration files in the coming months.\n` +
+        `Therefore, it is highly recommended that you migrate your "legacy" configuration to the new "flat" configuration format as soon as possible.\n` +
+        `Learn how at: https://eslint.org/docs/latest/use/configure/migration-guide`,
+
+    ApplyingFlatConfigFile:
+        `Applying the ESLint "flat" configuration file: %s`,
 
     UnableToCalculateBaseDirectory:
         `Could not calculate base directory for ESLint from the list of relevant targeted files to scan.\n` +

packages/code-analyzer-eslint-engine/src/run-eslint-worker-task.ts

@@ -19,7 +19,7 @@ export class RunESLintWorkerTask extends WorkerTask<RunESLintWorkerTaskInput, ES
     }
 
     protected async exec(input: RunESLintWorkerTaskInput): Promise<ESLint.LintResult[]> {
-        const eslint: ESLint = createESLint(input.engineConfig, input.eslintContext.baseDirectory, new Set(input.rulesToRun));
+        const eslint: ESLint = createESLint(input.engineConfig, input.eslintContext.baseDirectory, input.eslintContext.userConfigFile, new Set(input.rulesToRun));
         return await eslint.lintFiles(input.eslintContext.filesToScan);
     }
 }