feat: Improve config error messages

lib/config/flat-config-schema.js

@@ -212,6 +212,22 @@ function assertIsObject(value) {
     }
 }
 
+/**
+ * The error type when there's an eslintrc-style options in a flat config.
+ */
+class IncompatibleKeyError extends Error {
+
+    /**
+     * @param {string} key The invalid key.
+     */
+    constructor(key) {
+        super("This appears to be in eslintrc format rather than flat config format.");
+        this.messageTemplate = "eslintrc-incompat";
+        this.messageData = { key };
+    }
+}
+
+
 //-----------------------------------------------------------------------------
 // Low-Level Schemas
 //-----------------------------------------------------------------------------
@@ -438,11 +454,40 @@ const sourceTypeSchema = {
     }
 };
 
+/**
+ * Creates a schema that always throws an error. Useful for warning
+ * about eslintrc-style keys.
+ * @param {string} key The eslintrc key to create a schema for.
+ * @returns {ObjectPropertySchema} The schema.
+ */
+function createEslintrcSchema(key) {
+    return {
+        merge: "replace",
+        validate() {
+            throw new IncompatibleKeyError(key);
+        }
+    };
+}
+
 //-----------------------------------------------------------------------------
 // Full schema
 //-----------------------------------------------------------------------------
 
 exports.flatConfigSchema = {
+
+    // eslintrc-style keys that should warn
+    env: createEslintrcSchema("env"),
+    extends: createEslintrcSchema("extends"),
+    globals: createEslintrcSchema("globals"),
+    ignorePatterns: createEslintrcSchema("ignorePatterns"),
+    noInlineConfig: createEslintrcSchema("noInlineConfig"),
+    overrides: createEslintrcSchema("overrides"),
+    parser: createEslintrcSchema("parser"),
+    parserOptions: createEslintrcSchema("parserOptions"),
+    reportUnusedDisableDirectives: createEslintrcSchema("reportUnusedDisableDirectives"),
+    root: createEslintrcSchema("root"),
+
+    // flat config keys
     settings: deepObjectAssignSchema,
     linterOptions: {
         schema: {

messages/eslintrc-incompat.js

@@ -0,0 +1,116 @@
+"use strict";
+
+/* eslint consistent-return: 0 -- no default case */
+
+module.exports = function({ key }) {
+
+    switch (key) {
+        case "env":
+            return `
+A config object is using the "env" key, which is not supported in flat config system.
+
+Flat config uses "languageOptions.globals" to define global variables for your files.
+
+Please see the following page for information on how to convert your config object into the correct format:
+https://eslint.org/docs/latest/use/configure/migration-guide#configuring-language-options
+            `.trim();
+
+        case "extends":
+            return `
+A config object is using the "extends" key, which is not supported in flat config system.
+
+Instead of "extends", you can include config objects that you'd like to extend from directly in the flat config array.
+
+Please see the following page for more information:
+https://eslint.org/docs/latest/use/configure/configuration-files-new#using-predefined-configurations
+            `.trim();
+
+        case "globals":
+
+            return `
+A config object is using the "globals" key, which is not supported in flat config system.
+
+Flat config uses "languageOptions.globals" to define global variables for your files.
+
+Please see the following page for information on how to convert your config object into the correct format:
+https://eslint.org/docs/latest/use/configure/migration-guide#configuring-language-options
+            `.trim();
+
+        case "ignorePatterns":
+
+            return `
+A config object is using the "ignorePatterns" key, which is not supported in flat config system.
+
+Flat config uses "ignores" to specify files to ignore.
+
+Please see the following page for information on how to convert your config object into the correct format:
+https://eslint.org/docs/latest/use/configure/migration-guide#ignoring-files
+            `.trim();
+
+        case "noInlineConfig":
+
+            return `
+A config object is using the "noInlineConfig" key, which is not supported in flat config system.
+
+Flat config uses "linterOptions.noInlineConfig" to specify files to ignore.
+
+Please see the following page for information on how to convert your config object into the correct format:
+https://eslint.org/docs/latest/use/configure/migration-guide#linter-options
+            `.trim();
+
+        case "overrides":
+
+            return `
+A config object is using the "overrides" key, which is not supported in flat config system.
+
+Flat config is an array that acts like the eslintrc "overrides" array.
+
+Please see the following page for information on how to convert your config object into the correct format:
+https://eslint.org/docs/latest/use/configure/migration-guide#glob-based-configs
+            `.trim();
+
+        case "parser":
+
+            return `
+A config object is using the "parser" key, which is not supported in flat config system.
+
+Flat config uses "languageOptions.parser" to override the default parser.
+
+Please see the following page for information on how to convert your config object into the correct format:
+https://eslint.org/docs/latest/use/configure/migration-guide#configuring-language-options
+            `.trim();
+
+        case "parserOptions":
+
+            return `
+A config object is using the "parserOptions" key, which is not supported in flat config system.
+
+Flat config uses "languageOptions.parserOptions" to specify parser options.
+
+Please see the following page for information on how to convert your config object into the correct format:
+https://eslint.org/docs/latest/use/configure/migration-guide#configuring-language-options
+            `.trim();
+
+        case "reportUnusedDisableDirectives":
+
+            return `
+A config object is using the "reportUnusedDisableDirectives" key, which is not supported in flat config system.
+
+Flat config uses "linterOptions.reportUnusedDisableDirectives" to specify files to ignore.
+
+Please see the following page for information on how to convert your config object into the correct format:
+https://eslint.org/docs/latest/use/configure/migration-guide#linter-options
+            `.trim();
+
+        case "root":
+
+            return `
+A config object is using the "root" key, which is not supported in flat config system.
+
+Flat configs always act as if they are the root config file, so this key can be safely removed.
+            `.trim();
+
+        // no default
+    }
+
+};

tests/lib/config/flat-config-array.js

@@ -1938,5 +1938,33 @@ describe("FlatConfigArray", () => {
 
         });
 
+        describe("Invalid Keys", () => {
+
+            [
+                "env",
+                "extends",
+                "globals",
+                "ignorePatterns",
+                "noInlineConfig",
+                "overrides",
+                "parser",
+                "parserOptions",
+                "reportUnusedDisableDirectives",
+                "root"
+            ].forEach(key => {
+
+                it(`should error when a ${key} key is found`, async () => {
+                    await assertInvalidConfig([
+                        {
+                            [key]: "foo"
+                        }
+                    ], `Key "${key}": This appears to be in eslintrc format rather than flat config format.`);
+
+                });
+            });
+
+
+        });
+
     });
 });