@alexlit/lint-kit 111.0.0 → 112.0.0

package/packages/config-eslint/node_modules/@typescript-eslint/eslint-plugin/docs/rules/TEMPLATE.md

@@ -0,0 +1,36 @@
+---
+description: '<Description from rule metadata here>'
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+> 🛑 This file is source code, not the primary documentation location! 🛑
+>
+> See **https://typescript-eslint.io/rules/RULE_NAME_REPLACEME** for documentation.
+
+## Examples
+
+To fill out: tell us more about this rule.
+
+<Tabs>
+<TabItem value="❌ Incorrect">
+
+```ts
+// To fill out: incorrect code
+```
+
+</TabItem>
+<TabItem value="✅ Correct">
+
+```ts
+// To fill out: correct code
+```
+
+</TabItem>
+</Tabs>
+
+## When Not To Use It
+
+To fill out: why wouldn't you want to use this rule?
+For example if this rule requires a feature released in a certain TS version.

package/packages/config-eslint/node_modules/@typescript-eslint/eslint-plugin/docs/rules/adjacent-overload-signatures.mdx

@@ -0,0 +1,105 @@
+---
+description: 'Require that function overload signatures be consecutive.'
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+> 🛑 This file is source code, not the primary documentation location! 🛑
+>
+> See **https://typescript-eslint.io/rules/adjacent-overload-signatures** for documentation.
+
+Function overload signatures represent multiple ways a function can be called, potentially with different return types.
+It's typical for an interface or type alias describing a function to place all overload signatures next to each other.
+If Signatures placed elsewhere in the type are easier to be missed by future developers reading the code.
+
+## Examples
+
+<Tabs>
+<TabItem value="❌ Incorrect">
+
+```ts
+declare namespace Foo {
+  export function foo(s: string): void;
+  export function foo(n: number): void;
+  export function bar(): void;
+  export function foo(sn: string | number): void;
+}
+
+type Foo = {
+  foo(s: string): void;
+  foo(n: number): void;
+  bar(): void;
+  foo(sn: string | number): void;
+};
+
+interface Foo {
+  foo(s: string): void;
+  foo(n: number): void;
+  bar(): void;
+  foo(sn: string | number): void;
+}
+
+class Foo {
+  foo(s: string): void;
+  foo(n: number): void;
+  bar(): void {}
+  foo(sn: string | number): void {}
+}
+
+export function foo(s: string): void;
+export function foo(n: number): void;
+export function bar(): void;
+export function foo(sn: string | number): void;
+```
+
+</TabItem>
+<TabItem value="✅ Correct">
+
+```ts
+declare namespace Foo {
+  export function foo(s: string): void;
+  export function foo(n: number): void;
+  export function foo(sn: string | number): void;
+  export function bar(): void;
+}
+
+type Foo = {
+  foo(s: string): void;
+  foo(n: number): void;
+  foo(sn: string | number): void;
+  bar(): void;
+};
+
+interface Foo {
+  foo(s: string): void;
+  foo(n: number): void;
+  foo(sn: string | number): void;
+  bar(): void;
+}
+
+class Foo {
+  foo(s: string): void;
+  foo(n: number): void;
+  foo(sn: string | number): void {}
+  bar(): void {}
+}
+
+export function bar(): void;
+export function foo(s: string): void;
+export function foo(n: number): void;
+export function foo(sn: string | number): void;
+```
+
+</TabItem>
+</Tabs>
+
+## When Not To Use It
+
+It can sometimes be useful to place overload signatures alongside other meaningful parts of a type.
+For example, if each of a function's overloads corresponds to a different property, you might wish to put each overloads next to its corresponding property.
+You might consider using [ESLint disable comments](https://eslint.org/docs/latest/use/configure/rules#using-configuration-comments-1) for those specific situations instead of completely disabling this rule.
+
+## Related To
+
+- [`unified-signatures`](./unified-signatures.mdx)

package/packages/config-eslint/node_modules/@typescript-eslint/eslint-plugin/docs/rules/array-type.mdx

@@ -0,0 +1,123 @@
+---
+description: 'Require consistently using either `T[]` or `Array<T>` for arrays.'
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+> 🛑 This file is source code, not the primary documentation location! 🛑
+>
+> See **https://typescript-eslint.io/rules/array-type** for documentation.
+
+TypeScript provides two equivalent ways to define an array type: `T[]` and `Array<T>`.
+The two styles are functionally equivalent.
+Using the same style consistently across your codebase makes it easier for developers to read and understand array types.
+
+## Options
+
+The default config will enforce that all mutable and readonly arrays use the `'array'` syntax.
+
+### `"array"`
+
+Always use `T[]` or `readonly T[]` for all array types.
+
+<Tabs>
+<TabItem value="❌ Incorrect">
+
+```ts option='{ "default": "array" }'
+const x: Array<string> = ['a', 'b'];
+const y: ReadonlyArray<string> = ['a', 'b'];
+```
+
+</TabItem>
+<TabItem value="✅ Correct">
+
+```ts option='{ "default": "array" }'
+const x: string[] = ['a', 'b'];
+const y: readonly string[] = ['a', 'b'];
+```
+
+</TabItem>
+</Tabs>
+
+### `"generic"`
+
+Always use `Array<T>` or `ReadonlyArray<T>` for all array types.
+
+<Tabs>
+<TabItem value="❌ Incorrect">
+
+```ts option='{ "default": "generic" }'
+const x: string[] = ['a', 'b'];
+const y: readonly string[] = ['a', 'b'];
+```
+
+</TabItem>
+<TabItem value="✅ Correct">
+
+```ts option='{ "default": "generic" }'
+const x: Array<string> = ['a', 'b'];
+const y: ReadonlyArray<string> = ['a', 'b'];
+```
+
+</TabItem>
+</Tabs>
+
+### `"array-simple"`
+
+Use `T[]` or `readonly T[]` for simple types (i.e. types which are just primitive names or type references).
+Use `Array<T>` or `ReadonlyArray<T>` for all other types (union types, intersection types, object types, function types, etc).
+
+<Tabs>
+<TabItem value="❌ Incorrect">
+
+```ts option='{ "default": "array-simple" }'
+const a: (string | number)[] = ['a', 'b'];
+const b: { prop: string }[] = [{ prop: 'a' }];
+const c: (() => void)[] = [() => {}];
+const d: Array<MyType> = ['a', 'b'];
+const e: Array<string> = ['a', 'b'];
+const f: ReadonlyArray<string> = ['a', 'b'];
+```
+
+</TabItem>
+<TabItem value="✅ Correct">
+
+```ts option='{ "default": "array-simple" }'
+const a: Array<string | number> = ['a', 'b'];
+const b: Array<{ prop: string }> = [{ prop: 'a' }];
+const c: Array<() => void> = [() => {}];
+const d: MyType[] = ['a', 'b'];
+const e: string[] = ['a', 'b'];
+const f: readonly string[] = ['a', 'b'];
+```
+
+</TabItem>
+</Tabs>
+
+## Combination Matrix
+
+This matrix lists all possible option combinations and their expected results for different types of Arrays.
+
+| defaultOption  | readonlyOption | Array with simple type | Array with non simple type | Readonly array with simple type | Readonly array with non simple type |
+| -------------- | -------------- | ---------------------- | -------------------------- | ------------------------------- | ----------------------------------- |
+| `array`        |                | `number[]`             | `(Foo & Bar)[]`            | `readonly number[]`             | `readonly (Foo & Bar)[]`            |
+| `array`        | `array`        | `number[]`             | `(Foo & Bar)[]`            | `readonly number[]`             | `readonly (Foo & Bar)[]`            |
+| `array`        | `array-simple` | `number[]`             | `(Foo & Bar)[]`            | `readonly number[]`             | `ReadonlyArray<Foo & Bar>`          |
+| `array`        | `generic`      | `number[]`             | `(Foo & Bar)[]`            | `ReadonlyArray<number>`         | `ReadonlyArray<Foo & Bar>`          |
+| `array-simple` |                | `number[]`             | `Array<Foo & Bar>`         | `readonly number[]`             | `ReadonlyArray<Foo & Bar>`          |
+| `array-simple` | `array`        | `number[]`             | `Array<Foo & Bar>`         | `readonly number[]`             | `readonly (Foo & Bar)[]`            |
+| `array-simple` | `array-simple` | `number[]`             | `Array<Foo & Bar>`         | `readonly number[]`             | `ReadonlyArray<Foo & Bar>`          |
+| `array-simple` | `generic`      | `number[]`             | `Array<Foo & Bar>`         | `ReadonlyArray<number>`         | `ReadonlyArray<Foo & Bar>`          |
+| `generic`      |                | `Array<number>`        | `Array<Foo & Bar>`         | `ReadonlyArray<number>`         | `ReadonlyArray<Foo & Bar>`          |
+| `generic`      | `array`        | `Array<number>`        | `Array<Foo & Bar>`         | `readonly number[]`             | `readonly (Foo & Bar)[]`            |
+| `generic`      | `array-simple` | `Array<number>`        | `Array<Foo & Bar>`         | `readonly number[]`             | `ReadonlyArray<Foo & Bar>`          |
+| `generic`      | `generic`      | `Array<number>`        | `Array<Foo & Bar>`         | `ReadonlyArray<number>`         | `ReadonlyArray<Foo & Bar>`          |
+
+## When Not To Use It
+
+This rule is purely a stylistic rule for maintaining consistency in your project.
+You can turn it off if you don't want to keep a consistent style for array types.
+
+However, keep in mind that inconsistent style can harm readability in a project.
+We recommend picking a single option for this rule that works best for your project.

package/packages/config-eslint/node_modules/@typescript-eslint/eslint-plugin/docs/rules/await-thenable.mdx

@@ -0,0 +1,48 @@
+---
+description: 'Disallow awaiting a value that is not a Thenable.'
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+> 🛑 This file is source code, not the primary documentation location! 🛑
+>
+> See **https://typescript-eslint.io/rules/await-thenable** for documentation.
+
+A "Thenable" value is an object which has a `then` method, such as a Promise.
+The `await` keyword is generally used to retrieve the result of calling a Thenable's `then` method.
+
+If the `await` keyword is used on a value that is not a Thenable, the value is directly resolved immediately.
+While doing so is valid JavaScript, it is often a programmer error, such as forgetting to add parenthesis to call a function that returns a Promise.
+
+## Examples
+
+<Tabs>
+<TabItem value="❌ Incorrect">
+
+```ts
+await 'value';
+
+const createValue = () => 'value';
+await createValue();
+```
+
+</TabItem>
+<TabItem value="✅ Correct">
+
+```ts
+await Promise.resolve('value');
+
+const createValue = async () => 'value';
+await createValue();
+```
+
+</TabItem>
+</Tabs>
+
+## When Not To Use It
+
+If you want to allow code to `await` non-Promise values.
+For example, if your framework is in transition from one style of asynchronous code to another, it may be useful to include `await`s unnecessarily.
+This is generally not preferred but can sometimes be useful for visual consistency.
+You might consider using [ESLint disable comments](https://eslint.org/docs/latest/use/configure/rules#using-configuration-comments-1) for those specific situations instead of completely disabling this rule.

package/packages/config-eslint/node_modules/@typescript-eslint/eslint-plugin/docs/rules/ban-ts-comment.mdx

@@ -0,0 +1,165 @@
+---
+description: 'Disallow `@ts-<directive>` comments or require descriptions after directives.'
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+> 🛑 This file is source code, not the primary documentation location! 🛑
+>
+> See **https://typescript-eslint.io/rules/ban-ts-comment** for documentation.
+
+TypeScript provides several directive comments that can be used to alter how it processes files.
+Using these to suppress TypeScript compiler errors reduces the effectiveness of TypeScript overall.
+Instead, it's generally better to correct the types of code, to make directives unnecessary.
+
+The directive comments supported by TypeScript are:
+
+```ts
+// @ts-expect-error
+// @ts-ignore
+// @ts-nocheck
+// @ts-check
+```
+
+This rule lets you set which directive comments you want to allow in your codebase.
+
+## Options
+
+By default, only `@ts-check` is allowed, as it enables rather than suppresses errors.
+
+### `ts-expect-error`, `ts-ignore`, `ts-nocheck`, `ts-check` directives
+
+A value of `true` for a particular directive means that this rule will report if it finds any usage of said directive.
+
+<Tabs>
+<TabItem value="❌ Incorrect">
+
+```ts option='{ "ts-ignore": true }'
+if (false) {
+  // @ts-ignore: Unreachable code error
+  console.log('hello');
+}
+if (false) {
+  /*
+  @ts-ignore: Unreachable code error
+  */
+  console.log('hello');
+}
+```
+
+</TabItem>
+<TabItem value="✅ Correct">
+
+```ts option='{ "ts-ignore": true }'
+if (false) {
+  // Compiler warns about unreachable code error
+  console.log('hello');
+}
+```
+
+</TabItem>
+</Tabs>
+
+### `allow-with-description`
+
+A value of `'allow-with-description'` for a particular directive means that this rule will report if it finds a directive that does not have a description following the directive (on the same line).
+
+For example, with `{ 'ts-expect-error': 'allow-with-description' }`:
+
+<Tabs>
+<TabItem value="❌ Incorrect">
+
+```ts option='{ "ts-expect-error": "allow-with-description" }'
+if (false) {
+  // @ts-expect-error
+  console.log('hello');
+}
+if (false) {
+  /* @ts-expect-error */
+  console.log('hello');
+}
+```
+
+</TabItem>
+<TabItem value="✅ Correct">
+
+```ts option='{ "ts-expect-error": "allow-with-description" }'
+if (false) {
+  // @ts-expect-error: Unreachable code error
+  console.log('hello');
+}
+if (false) {
+  /*
+  @ts-expect-error: Unreachable code error
+  */
+  console.log('hello');
+}
+```
+
+</TabItem>
+</Tabs>
+### `descriptionFormat`
+
+For each directive type, you can specify a custom format in the form of a regular expression. Only description that matches the pattern will be allowed.
+
+For example, with `{ 'ts-expect-error': { descriptionFormat: '^: TS\\d+ because .+$' } }`:
+
+<Tabs>
+<TabItem value="❌ Incorrect">
+
+{/* prettier-ignore */}
+```ts option='{ "ts-expect-error": { "descriptionFormat": "^: TS\\\\d+ because .+$" } }'
+// @ts-expect-error: the library definition is wrong
+const a = doSomething('hello');
+```
+
+</TabItem>
+<TabItem value="✅ Correct">
+
+{/* prettier-ignore */}
+```ts option='{ "ts-expect-error": { "descriptionFormat": "^: TS\\\\d+ because .+$" } }'
+// @ts-expect-error: TS1234 because the library definition is wrong
+const a = doSomething('hello');
+```
+
+</TabItem>
+</Tabs>
+
+### `minimumDescriptionLength`
+
+Use `minimumDescriptionLength` to set a minimum length for descriptions when using the `allow-with-description` option for a directive.
+
+For example, with `{ 'ts-expect-error': 'allow-with-description', minimumDescriptionLength: 10 }` the following pattern is:
+
+<Tabs>
+<TabItem value="❌ Incorrect">
+
+```ts option='{ "ts-expect-error": "allow-with-description", "minimumDescriptionLength": 10 }'
+if (false) {
+  // @ts-expect-error: TODO
+  console.log('hello');
+}
+```
+
+</TabItem>
+<TabItem value="✅ Correct">
+
+```ts option='{ "ts-expect-error": "allow-with-description", "minimumDescriptionLength": 10 }'
+if (false) {
+  // @ts-expect-error The rationale for this override is described in issue #1337 on GitLab
+  console.log('hello');
+}
+```
+
+</TabItem>
+</Tabs>
+
+## When Not To Use It
+
+If your project or its dependencies were not architected with strong type safety in mind, it can be difficult to always adhere to proper TypeScript semantics.
+You might consider using [ESLint disable comments](https://eslint.org/docs/latest/use/configure/rules#using-configuration-comments-1) for those specific situations instead of completely disabling this rule.
+
+## Further Reading
+
+- TypeScript [Type Checking JavaScript Files](https://www.typescriptlang.org/docs/handbook/type-checking-javascript-files.html)

package/packages/config-eslint/node_modules/@typescript-eslint/eslint-plugin/docs/rules/ban-tslint-comment.mdx

@@ -0,0 +1,45 @@
+---
+description: 'Disallow `// tslint:<rule-flag>` comments.'
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+> 🛑 This file is source code, not the primary documentation location! 🛑
+>
+> See **https://typescript-eslint.io/rules/ban-tslint-comment** for documentation.
+
+Useful when migrating from TSLint to ESLint. Once TSLint has been removed, this rule helps locate TSLint annotations (e.g. `// tslint:disable`).
+
+> See the [TSLint rule flags docs](https://palantir.github.io/tslint/usage/rule-flags) for reference.
+
+## Examples
+
+<Tabs>
+<TabItem value="❌ Incorrect">
+
+```ts
+/* tslint:disable */
+/* tslint:enable */
+/* tslint:disable:rule1 rule2 rule3... */
+/* tslint:enable:rule1 rule2 rule3... */
+// tslint:disable-next-line
+someCode(); // tslint:disable-line
+// tslint:disable-next-line:rule1 rule2 rule3...
+```
+
+</TabItem>
+<TabItem value="✅ Correct">
+
+```ts
+// This is a comment that just happens to mention tslint
+/* This is a multiline comment that just happens to mention tslint */
+someCode(); // This is a comment that just happens to mention tslint
+```
+
+</TabItem>
+</Tabs>
+
+## When Not To Use It
+
+If you are still using TSLint alongside ESLint.

package/packages/config-eslint/node_modules/@typescript-eslint/eslint-plugin/docs/rules/ban-types.mdx

@@ -0,0 +1,138 @@
+---
+description: 'Disallow certain types.'
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+> 🛑 This file is source code, not the primary documentation location! 🛑
+>
+> See **https://typescript-eslint.io/rules/ban-types** for documentation.
+
+Some built-in types have aliases, while some types are considered dangerous or harmful.
+It's often a good idea to ban certain types to help with consistency and safety.
+
+This rule bans specific types and can suggest alternatives.
+Note that it does not ban the corresponding runtime objects from being used.
+
+## Examples
+
+Examples of code with the default options:
+
+<Tabs>
+<TabItem value="❌ Incorrect">
+
+```ts
+// use lower-case primitives for consistency
+const str: String = 'foo';
+const bool: Boolean = true;
+const num: Number = 1;
+const symb: Symbol = Symbol('foo');
+const bigInt: BigInt = 1n;
+
+// use a proper function type
+const func: Function = () => 1;
+
+// use safer object types
+const lowerObj: Object = {};
+const capitalObj: Object = { a: 'string' };
+
+const curly1: {} = 1;
+const curly2: {} = { a: 'string' };
+```
+
+</TabItem>
+<TabItem value="✅ Correct">
+
+```ts
+// use lower-case primitives for consistency
+const str: string = 'foo';
+const bool: boolean = true;
+const num: number = 1;
+const symb: symbol = Symbol('foo');
+const bigInt: bigint = 1n;
+
+// use a proper function type
+const func: () => number = () => 1;
+
+// use safer object types
+const lowerObj: object = {};
+const capitalObj: { a: string } = { a: 'string' };
+
+const curly1: number = 1;
+const curly2: Record<'a', string> = { a: 'string' };
+```
+
+</TabItem>
+</Tabs>
+
+## Options
+
+The default options provide a set of "best practices", intended to provide safety and standardization in your codebase:
+
+- Don't use the upper-case primitive types, you should use the lower-case types for consistency.
+- Avoid the `Function` type, as it provides little safety for the following reasons:
+  - It provides no type safety when calling the value, which means it's easy to provide the wrong arguments.
+  - It accepts class declarations, which will fail when called, as they are called without the `new` keyword.
+- Avoid the `Object` and `{}` types, as they mean "any non-nullish value".
+  - This is a point of confusion for many developers, who think it means "any object type".
+  - See [this comment for more information](https://github.com/typescript-eslint/typescript-eslint/issues/2063#issuecomment-675156492).
+
+<details>
+<summary>Default Options</summary>
+
+{/* Inject default options */}
+
+</details>
+
+### `types`
+
+An object whose keys are the types you want to ban, and the values are error messages.
+
+The type can either be a type name literal (`Foo`), a type name with generic parameter instantiation(s) (`Foo<Bar>`), the empty object literal (`{}`), or the empty tuple type (`[]`).
+
+The values can be:
+
+- A string, which is the error message to be reported; or
+- `false` to specifically un-ban this type (useful when you are using `extendDefaults`); or
+- An object with the following properties:
+  - `message: string` - the message to display when the type is matched.
+  - `fixWith?: string` - a string to replace the banned type with when the fixer is run. If this is omitted, no fix will be done.
+  - `suggest?: string[]` - a list of suggested replacements for the banned type.
+
+### `extendDefaults`
+
+If you're specifying custom `types`, you can set this to `true` to extend the default `types` configuration. This is a convenience option to save you copying across the defaults when adding another type.
+
+If this is `false`, the rule will _only_ use the types defined in your configuration.
+
+Example configuration:
+
+```jsonc
+{
+  "@typescript-eslint/ban-types": [
+    "error",
+    {
+      "types": {
+        // add a custom message to help explain why not to use it
+        "Foo": "Don't use Foo because it is unsafe",
+
+        // add a custom message, AND tell the plugin how to fix it
+        "OldAPI": {
+          "message": "Use NewAPI instead",
+          "fixWith": "NewAPI",
+        },
+
+        // un-ban a type that's banned by default
+        "{}": false,
+      },
+      "extendDefaults": true,
+    },
+  ],
+}
+```
+
+## When Not To Use It
+
+If your project is a rare one that intentionally deals with the class equivalents of primitives, it might not be worthwhile to enable the default `ban-types` options.
+You might consider using [ESLint disable comments](https://eslint.org/docs/latest/use/configure/rules#using-configuration-comments-1) for those specific situations instead of completely disabling this rule.

package/packages/config-eslint/node_modules/@typescript-eslint/eslint-plugin/docs/rules/block-spacing.mdx

@@ -0,0 +1,13 @@
+---
+description: 'Disallow or enforce spaces inside of blocks after opening block and before closing block.'
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+> 🛑 This file is source code, not the primary documentation location! 🛑
+>
+> See **https://typescript-eslint.io/rules/block-spacing** for documentation.
+
+This rule extends the base [`eslint/block-spacing`](https://eslint.org/docs/rules/block-spacing) rule.
+This version adds support for TypeScript related blocks (interfaces, object type literals and enums).

package/packages/config-eslint/node_modules/@typescript-eslint/eslint-plugin/docs/rules/brace-style.mdx

@@ -0,0 +1,13 @@
+---
+description: 'Enforce consistent brace style for blocks.'
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+> 🛑 This file is source code, not the primary documentation location! 🛑
+>
+> See **https://typescript-eslint.io/rules/brace-style** for documentation.
+
+This rule extends the base [`eslint/brace-style`](https://eslint.org/docs/rules/brace-style) rule.
+It adds support for `enum`, `interface`, `namespace` and `module` declarations.