Support augmented global properties (#238)

Co-authored-by: antfu <[email protected]>

Author: Shinigami92

README.md

@@ -47,6 +47,12 @@ pnpm add --save-dev eslint eslint-define-config
 
 ```ts
 // @ts-check
+
+// To activate auto-suggestions for Rules of specific plugins, you need to add a `/// <reference types="eslint-plugin-PLUGIN_NAME/define-config-support" />` comment.
+// ⚠️ This feature is very new and requires the support of the respective plugin owners.
+
+/// <reference types="@typescript-eslint/eslint-plugin/define-config-support" />
+
 const { defineConfig } = require('eslint-define-config');
 
 module.exports = defineConfig({
@@ -97,6 +103,40 @@ _Click on the thumbnail to play the video_
   <img src="https://user-images.githubusercontent.com/7195563/112726343-30c56b00-8f1d-11eb-9b92-260c530caf1b.png" alt="Video" width="600px"/>
 </a>
 
+## Want to support your own plugin?
+
+:warning: **This feature is very new and requires the support of the respective plugin owners**
+
+Add a `declare module` to your plugin package like this:
+
+```ts
+declare module 'eslint-define-config' {
+  export interface CustomRuleOptions {
+    /**
+     * Require consistently using either `T[]` or `Array<T>` for arrays.
+     *
+     * @see [array-type](https://typescript-eslint.io/rules/array-type)
+     */
+    '@typescript-eslint/array-type': [
+      {
+        default?: 'array' | 'generic' | 'array-simple';
+        readonly?: 'array' | 'generic' | 'array-simple';
+      },
+    ];
+
+    // ... more Rules
+  }
+}
+```
+
+There are other interfaces that can be extended.
+
+- `CustomExtends`
+- `CustomParserOptions`
+- `CustomParsers`
+- `CustomPlugins`
+- `CustomSettings`
+
 # Credits
 
 - [Proposal Idea](https://github.com/eslint/eslint/issues/14249)

src/config/extends/index.d.ts

@@ -21,6 +21,30 @@ import type { VuePugExtends } from './eslint-plugin-vue-pug';
 import type { IntlifyVueI18nExtends } from './intlify-vue-i18n';
 import type { TypescriptEslintExtends } from './typescript-eslint';
 
+/**
+ * This is a special exported interface for other packages to declare
+ * additional extensions that should bail out for eslint extensions. For example
+ * `'@typescript-eslint/eslint-plugin'` can declare it like so in its `d.ts`:
+ *
+ * ```ts
+ * declare module 'eslint-define-config' {
+ *   export interface CustomExtends {
+ *     'plugin:@typescript-eslint/all': void;
+ *     'plugin:@typescript-eslint/base': void;
+ *     'plugin:@typescript-eslint/disable-type-checked': void;
+ *     'plugin:@typescript-eslint/eslint-recommended': void;
+ *     'plugin:@typescript-eslint/recommended-type-checked': void;
+ *     'plugin:@typescript-eslint/recommended': void;
+ *     'plugin:@typescript-eslint/strict-type-checked': void;
+ *     'plugin:@typescript-eslint/strict': void;
+ *     'plugin:@typescript-eslint/stylistic-type-checked': void;
+ *     'plugin:@typescript-eslint/stylistic': void;
+ *   }
+ * }
+ * ```
+ */
+export interface CustomExtends {}
+
 /**
  * All known extends.
  */
@@ -46,6 +70,8 @@ export type KnownExtends = LiteralUnion<
   | VitestExtends
   | VueExtends
   | VuePugExtends
+  // eslint-disable-next-line @typescript-eslint/no-redundant-type-constituents
+  | keyof CustomExtends
 >;
 
 /**

src/config/index.d.ts

@@ -83,7 +83,7 @@ export interface ESLintConfig {
    *
    * @see [Rules](https://eslint.org/docs/latest/user-guide/configuring/rules)
    */
-  rules?: Rules;
+  rules?: Partial<Rules>;
 
   /**
    * Overrides.

src/config/overrides.d.ts

@@ -80,7 +80,7 @@ export interface Override {
    *
    * @see [Rules](https://eslint.org/docs/user-guide/configuring/rules)
    */
-  rules?: Rules;
+  rules?: Partial<Rules>;
 
   /**
    * Settings.

src/config/plugin.d.ts

@@ -1,5 +1,20 @@
 import type { LiteralUnion } from '../utility-types';
 
+/**
+ * This is a special exported interface for other packages to declare
+ * additional plugins that should bail out for eslint plugins. For example
+ * `'@typescript-eslint/eslint-plugin'` can declare it like so in its `d.ts`:
+ *
+ * ```ts
+ * declare module 'eslint-define-config' {
+ *   export interface CustomPlugins {
+ *     '@typescript-eslint': void;
+ *   }
+ * }
+ * ```
+ */
+export interface CustomPlugins {}
+
 /** Plugin. */
 export type Plugin = LiteralUnion<
   | '@graphql-eslint'
@@ -20,4 +35,6 @@ export type Plugin = LiteralUnion<
   | 'unicorn'
   | 'vitest'
   | 'vue'
+  // eslint-disable-next-line @typescript-eslint/no-redundant-type-constituents
+  | keyof CustomPlugins
 >;

src/config/settings/index.d.ts

@@ -5,6 +5,23 @@ import type { MdxSettings } from './mdx';
 import type { NodeSettings } from './node';
 import type { ReactSettings } from './react';
 
+/**
+ * This is a special exported interface for other packages to declare
+ * additional settings that should bail out for eslint settings. For example
+ * `'eslint-plugin-jsx-a11y'` can declare it like so in its `d.ts`:
+ *
+ * ```ts
+ * declare module 'eslint-define-config' {
+ *   export interface CustomSettings {
+ *     'jsx-a11y': {
+ *       components?: Record<string, string>;
+ *     };
+ *   }
+ * }
+ * ```
+ */
+export interface CustomSettings {}
+
 /**
  * Settings.
  */
@@ -15,4 +32,5 @@ export interface Settings
     MdxSettings,
     NodeSettings,
     ReactSettings,
+    Partial<CustomSettings>,
     Partial<Record<string, unknown>> {}

src/flat-config/index.d.ts

@@ -54,7 +54,7 @@ export interface FlatESLintConfigItem {
    *
    * @see [Configuring rules](https://eslint.org/docs/latest/user-guide/configuring/configuration-files-new#configuring-rules)
    */
-  rules?: Rules;
+  rules?: Partial<Rules>;
 
   /**
    * An object containing name-value pairs of information that should be available to all rules.

src/parser-options.d.ts

@@ -132,20 +132,80 @@ export type DebugLevel =
   | boolean
   | Array<'eslint' | 'typescript' | 'typescript-eslint'>;
 
+/**
+ * This is a special exported interface for other packages to declare
+ * additional parsers that should bail out for eslint parsers. For example
+ * `'@typescript-eslint/eslint-plugin'` can declare it like so in its `d.ts`:
+ *
+ * ```ts
+ * declare module 'eslint-define-config' {
+ *   export interface CustomParsers {
+ *     '@typescript-eslint/parser': void;
+ *   }
+ * }
+ * ```
+ */
+export interface CustomParsers {}
+
 /** Parser. */
 export type Parser = LiteralUnion<
   | 'babel-eslint'
   | '@typescript-eslint/parser'
   | 'jsonc-eslint-parser'
   | 'vue-eslint-parser'
+  // eslint-disable-next-line @typescript-eslint/no-redundant-type-constituents
+  | keyof CustomParsers
 >;
 
+/**
+ * This is a special exported interface for other packages to declare
+ * additional parser options that should bail out for eslint parser options. For example
+ * `@typescript-eslint/eslint-plugin` can declare it like so in its `d.ts`:
+ *
+ * ```ts
+ * declare module 'eslint-define-config' {
+ *   export interface CustomParserOptions {
+ *     /**
+ *      * This option allows you to provide the root directory for relative tsconfig paths specified in the `project` option above.
+ *      *
+ *      * \@see [tsconfigRootDir](https://typescript-eslint.io/architecture/parser/#tsconfigrootdir)
+ *      *\/
+ *     tsconfigRootDir?: string;
+ *
+ *     useJSXTextNode?: boolean;
+ *
+ *     /**
+ *      * This option allows you to toggle the warning that the parser will give you if you use a version of TypeScript which is not explicitly supported.
+ *      *
+ *      * \@default true
+ *      *
+ *      * \@see [warnOnUnsupportedTypeScriptVersion](https://typescript-eslint.io/architecture/parser/#warnonunsupportedtypescriptversion)
+ *      *\/
+ *     warnOnUnsupportedTypeScriptVersion?: boolean;
+ *
+ *     /**
+ *      * This option allow you to tell parser to act as if `emitDecoratorMetadata: true` is set in `tsconfig.json`, but without [type-aware linting](https://typescript-eslint.io/linting/typed-linting).
+ *      * In other words, you don't have to specify `parserOptions.project` in this case, making the linting process faster.
+ *      *
+ *      * \@default undefined
+ *      *
+ *      * \@see [emitDecoratorMetadata](https://typescript-eslint.io/architecture/parser/#emitdecoratormetadata)
+ *      *\/
+ *     emitDecoratorMetadata?: boolean;
+ *   }
+ * }
+ * ```
+ */
+export interface CustomParserOptions {}
+
 /**
  * Parser options.
  *
  * @see [Specifying Parser Options](https://eslint.org/docs/user-guide/configuring/language-options#specifying-parser-options)
  */
-export interface ParserOptions extends Partial<Record<string, unknown>> {
+export interface ParserOptions
+  extends Partial<CustomParserOptions>,
+    Partial<Record<string, unknown>> {
   /**
    * Accepts any valid ECMAScript version number or `'latest'`:
    *

src/rules/index.d.ts

@@ -23,34 +23,67 @@ import type { VueI18nRules } from './vue-i18n';
 import type { VuePugRules } from './vue-pug';
 import type { YmlRules } from './yml';
 
+/**
+ * This is a special exported interface for other packages to declare
+ * additional types that should bail out for eslint rules. For example
+ * `@typescript-eslint/eslint-plugin` can declare it like so in its `d.ts`:
+ *
+ * ```ts
+ * declare module 'eslint-define-config' {
+ *   export interface CustomRuleOptions {
+ *     /**
+ *      * Require consistently using either `T[]` or `Array<T>` for arrays.
+ *      *
+ *      * \@see [array-type](https://typescript-eslint.io/rules/array-type)
+ *      *\/
+ *     '@typescript-eslint/array-type': [
+ *       {
+ *         default?: 'array' | 'generic' | 'array-simple';
+ *         readonly?: 'array' | 'generic' | 'array-simple';
+ *       },
+ *     ];
+ *
+ *     // ... more Rules
+ *   }
+ * }
+ * ```
+ */
+export interface CustomRuleOptions {}
+
+type CustomRules = {
+  [TRuleName in keyof CustomRuleOptions]: RuleConfig<
+    CustomRuleOptions[TRuleName]
+  >;
+};
+
 /**
  * Rules.
  *
  * @see [Rules](https://eslint.org/docs/user-guide/configuring/rules)
  */
-export type Rules = Partial<
-  DeprecationRules &
-    EslintRules &
-    EslintCommentsRules &
-    GraphQLRules &
-    ImportRules &
-    JSDocRules &
-    JsoncRules &
-    JsxA11yRules &
-    NodeRules &
-    NRules &
-    PromiseRules &
-    ReactHooksRules &
-    ReactRules &
-    SonarJSRules &
-    SpellcheckRules &
-    TestingLibraryRules &
-    TypeScriptRules &
-    UnicornRules &
-    VitestRules &
-    VueRules &
-    VueI18nRules &
-    VuePugRules &
-    YmlRules &
-    Record<string, RuleConfig>
->;
+export interface Rules
+  extends CustomRules,
+    DeprecationRules,
+    EslintRules,
+    EslintCommentsRules,
+    GraphQLRules,
+    ImportRules,
+    JSDocRules,
+    JsoncRules,
+    JsxA11yRules,
+    NodeRules,
+    NRules,
+    PromiseRules,
+    ReactHooksRules,
+    ReactRules,
+    SonarJSRules,
+    SpellcheckRules,
+    TestingLibraryRules,
+    TypeScriptRules,
+    UnicornRules,
+    VitestRules,
+    VueRules,
+    VueI18nRules,
+    VuePugRules,
+    YmlRules,
+    Record<string, RuleConfig> {}