Movatterモバイル変換

[0]ホーム
URL:

Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly

 Sign up
Appearance settings

docs: fleshed out dedicated Architecture section#4124

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to ourterms of service andprivacy statement. We’ll occasionally send you account related emails.

Already on GitHub?Sign in to your account

Merged
Merged
Show file tree
Hide file tree
Changes fromall commits
Commits
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions.cspell.json
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -103,6 +103,7 @@
"typedef",
"typedefs",
"unfixable",
"unoptimized",
"unprefixed",
"Zacher"
],
Expand Down
19 changes: 7 additions & 12 deletionsREADME.md
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -20,21 +20,16 @@
👆
</p>

---

## Packages included in this project

- [`@typescript-eslint/eslint-plugin`](./packages/eslint-plugin/) - An ESLint-plugin with many lint rules for TypeScript features, as well as type-aware lint rules.

- [`@typescript-eslint/parser`](./packages/parser/) - A ESLint-parser which enables ESLint to be able to understand TypeScript syntax. It's powered by our `typescript-estree` package.

- [`@typescript-eslint/eslint-plugin-tslint`](./packages/eslint-plugin-tslint) - An ESLint-plugin that allows you to bridge ESLint and TSLint to help you migrate from TSLint to ESLint.

- [`@typescript-eslint/experimental-utils`](./packages/experimental-utils) - Public utilities for working ESLint and for writing ESLint-plugins in TypeScript.

- [`@typescript-eslint/typescript-estree`](./packages/typescript-estree/) - A parser which takes TypeScript source code and produces an [ESTree](https://github.com/estree/estree)-compatible AST.
See https://typescript-eslint.io/docs/development/architecture/packages for more details.

- [`@typescript-eslint/scope-manager`](./packages/scope-manager) - An [`eslint-scope`](https://github.com/eslint/eslint-scope)-compatible scope analyser that can understand TypeScript language features such as types, enums and namespaces.
- [`@typescript-eslint/eslint-plugin`](./packages/eslint-plugin)
- [`@typescript-eslint/parser`](./packages/parser)
- [`@typescript-eslint/eslint-plugin-tslint`](./packages/eslint-plugin-tslint)
- [`@typescript-eslint/experimental-utils`](./packages/experimental-utils)
- [`@typescript-eslint/typescript-estree`](./packages/typescript-estree)
- [`@typescript-eslint/scope-manager`](./packages/scope-manager)

## Versioning

Expand Down
2 changes: 1 addition & 1 deletiondocs/getting-started/README.md → docs/README.md
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -10,4 +10,4 @@ The docs are broken down into the following categories:

- [I want to lint my TypeScript codebase.](./linting/README.md)

- [(TODO)I want towrite an ESLint plugin in TypeScript.](./plugin-development/README.md)
- [I want todevelop an ESLint plugin in TypeScript.](./development/CUSTOM_RULES.md)
268 changes: 268 additions & 0 deletionsdocs/development/CUSTOM_RULES.md
View file
Open in desktop
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,268 @@
---
id: custom-rules
sidebar_label: Custom Rules
title: Custom Rules
---

:::important
You should be familiar with [ESLint's developer guide](https://eslint.org/docs/developer-guide) and [Development > Architecture](./architecture/asts) before writing custom rules.
:::

As long as you are using `@typescript-eslint/parser` as the `parser` in your ESLint configuration, custom ESLint rules generally work the same way for JavaScript and TypeScript code.
The main two changes to custom rules writing are:

- [AST Extensions](#ast-extensions): targeting TypeScript-specific syntax in your rule selectors
- [Typed Rules](#typed-rules): using the TypeScript type checker to inform rule logic

## AST Extensions

`@typescript-eslint/estree` creates AST nodes for TypeScript syntax with names that begin with `TS`, such as `TSInterfaceDeclaration` and `TSTypeAnnotation`.
These nodes are treated just like any other AST node.
You can query for them in your rule selectors.

This rule written in JavaScript bans interfaces that start with a lower-case letter:

```js
export const rule = {
create(context) {
return {
TSInterfaceDeclaration(node) {
if (/[a-z]/.test(node.id.name[0])) {
context.report({
messageId: 'uppercase',
node: node.id,
});
}
},
};
},
meta: {
docs: {
category: 'Best Practices',
description: 'Interface names should start with an upper-case letter.',
},
messages: {
uppercase: 'Start this name with an upper-case letter.',
},
type: 'suggestion',
schema: [],
},
};
```

### Writing Rules in TypeScript

The `@typescript-eslint/experimental-utils` package acts as a replacement package for `eslint` that exports all the same objects and types, but with typescript-eslint support.

:::caution
`@types/eslint` types are based on `@types/estree` and do not recognize typescript-eslint nodes and properties.
You should generally not need to import from `eslint` when writing custom typescript-eslint rules in TypeScript.
:::

#### Rule Types

`@typescript-eslint/experimental-utils` exports a `RuleModule` interface that allows specifying generics for:

- `MessageIds`: a union of string literal message IDs that may be reported
- `Options`: what options users may configure for the rule

```ts
import { TSESLint } from '@typescript-eslint/experimental-utils';

export const rule: TSESLint.RuleModule<'uppercase', []> = {
create(context /* : Readonly<RuleContext<TMessageIds, TOptions>> */) {
// ...
},
};
```

For groups of rules that share a common documentation URL, a `RuleCreator` function is exported.
It takes in a function that transforms a rule name into its documentation URL, then returns a function that takes in a rule module object.
The returned function is able to infer message IDs from `meta.messages`.

```ts
import { ESLintUtils } from '@typescript-eslint/experimental-utils';

const createRule = ESLintUtils.RuleCreator(
name => `https://example.com/rule/${name}`,
);

// Type: const rule: RuleModule<"uppercase", ...>
export const rule = createRule({
create(context) {
// ...
},
meta: {
messages: {
uppercase: 'Start this name with an upper-case letter.',
},
// ...
},
});
```

#### Node Types

TypeScript types for nodes exist in a `TSESTree` namespace exported by `@typescript-eslint/experimental-utils`.
The above rule body could be better written in TypeScript with a type annotation on the `node`:

```ts
import { TSESLint, TSESTree } from '@typescript-eslint/experimental-utils';

// ...

export const rule = createRule({
create(context) {
return {
TSInterfaceDeclaration(node: TSESTree.TSInterfaceDeclaration) {
// ...
},
};
},
// ...
});
```

An `AST_NODE_TYPES` enum is exported as well to hold the values for AST node `type` properties.
`TSESTree.Node` is available as union type that uses its `type` member as a discriminant.

For example, checking `node.type` can narrow down the type of the `node`:

```ts
import {
AST_NODE_TYPES,
TSESTree,
} from '@typescript-eslint/experimental-utils';

export function describeNode(node: TSESTree.Node): string {
switch (node.type) {
case AST_NODE_TYPES.ArrayExpression:
return `Array containing ${node.elements.map(describeNode).join(', ')}`;

case AST_NODE_TYPES.Literal:
return `Literal value ${node.raw}`;

default:
return '🤷';
}
}
```

## Type Checking

:::tip
Read TypeScript's [Compiler APIs > Using the Type Checker](https://github.com/microsoft/TypeScript/wiki/Using-the-Compiler-API#using-the-type-checker) section for how to use a program's type checker.
:::

The biggest addition typescript-eslint brings to ESLint rules is the ability to use TypeScript's type checker APIs.

`@typescript-eslint/experimental-utils` exports an `ESLintUtils` namespace containing a `getParserServices` function that takes in an ESLint context and returns a `parserServices` object.

That `parserServices` object contains:

- `program`: A full TypeScript `ts.Program` object
- `esTreeNodeToTSNodeMap`: Map of `@typescript-eslint/estree` `TSESTree.Node` nodes to their TypeScript `ts.Node` equivalents
- `tsNodeToESTreeNodeMap`: Map of TypeScript `ts.Node` nodes to their `@typescript-eslint/estree` `TSESTree.Node` equivalents

By mapping from ESTree nodes to TypeScript nodes and retrieving the TypeScript program from the parser services, rules are able to ask TypeScript for full type information on those nodes.

This rule bans for-of looping over an enum by using the type-checker via typescript-eslint and TypeScript APIs:

```ts
import { ESLintUtils } from '@typescript-eslint/experimental-utils';
import * as ts from 'typescript';
import * as tsutils from 'tsutils';

export const rule: eslint.Rule.RuleModule = {
create(context) {
return {
ForOfStatement(node) {
// 1. Grab the TypeScript program from parser services
const parserServices = ESLintUtils.getParserServices(context);
const checker = parserServices.program.getTypeChecker();

// 2. Find the backing TS node for the ES node, then that TS type
const originalNode = parserServices.esTreeNodeToTSNodeMap.get(
node.right,
);
const nodeType = checker.getTypeAtLocation(node);

// 3. Check the TS node type using the TypeScript APIs
if (tsutils.isTypeFlagSet(nodeType, ts.TypeFlags.EnumLike)) {
context.report({
messageId: 'loopOverEnum',
node: node.right,
});
}
},
};
},
meta: {
docs: {
category: 'Best Practices',
description: 'Avoid looping over enums.',
},
messages: {
loopOverEnum: 'Do not loop over enums.',
},
type: 'suggestion',
schema: [],
},
};
```

## Testing

`@typescript-eslint/experimental-utils` exports a `RuleTester` with a similar API to the built-in [ESLint `RuleTester`](https://eslint.org/docs/developer-guide/nodejs-api#ruletester).
It should be provided with the same `parser` and `parserOptions` you would use in your ESLint configuration.

### Testing Untyped Rules

For rules that don't need type information, passing just the `parser` will do:

```ts
import { ESLintUtils } from '@typescript-eslint/experimental-utils';
import rule from './my-rule';

const ruleTester = new ESLintUtils.RuleTester({
parser: '@typescript-eslint/parser',
});

ruleTester.run('my-rule', rule {
valid: [/* ... */],
invalid: [/* ... */],
});
```

### Testing Typed Rules

For rules that do need type information, `parserOptions` must be passed in as well.
Tests must have at least an absolute `tsconfigRootDir` path provided as well as a relative `project` path from that directory:

```ts
import { ESLintUtils } from '@typescript-eslint/experimental-utils';
import rule from './my-typed-rule';

const ruleTester = new ESLintUtils.RuleTester({
parser: '@typescript-eslint/parser',
parserOptions: {
project: './tsconfig.json',
tsconfigRootDir: __dirname,
}
});

ruleTester.run('my-typed-rule', rule {
valid: [/* ... */],
invalid: [/* ... */],
});
```

:::note
For now, `ESLintUtils.RuleTester` requires the following physical files be present on disk for typed rules:

- `tsconfig.json`: tsconfig used as the test "project"
- One of the following two files:
- `file.ts`: blank test file used for normal TS tests
- `file.tsx`: blank test file used for tests with `parserOptions: { ecmaFeatures: { jsx: true } }`

:::
51 changes: 51 additions & 0 deletionsdocs/development/architecture/ASTS.md
View file
Open in desktop
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
---
id: asts
title: ASTs
sidebar_label: ASTs
---

## Abstract Syntax Trees (AST)s

Parsers such as those in ESLint and TypeScript read in the text of source code and parse it into a standard format they can reason about known as an **Abstract Syntax Tree** (AST).
ASTs are called such because although they might contain information on the location of constructs within source code, they are an abstract representation that cares more about the semantic structure.

For example, given this line of code:

```js
1 + 2;
```

ESLint would natively understand it as an object like:

```json
{
"type": "ExpressionStatement",
"expression": {
"type": "BinaryExpression",
"left": {
"type": "Literal",
"value": 1,
"raw": "1"
},
"operator": "+",
"right": {
"type": "Literal",
"value": 2,
"raw": "2"
}
}
}
```

ESLint uses an AST format known as **[`estree`]**.

ESTree is more broadly used than just for ESLint -- it is the de facto community standard.
ESLint's built-in parser that outputs an `estree`-shaped AST is also a separate package, called **[`espree`]**.

:::note
You can play more with various ASTs such as ESTree on [astexplorer.net] and read more details on their [Wikipedia article](https://en.wikipedia.org/wiki/Abstract_syntax_tree).
:::

[astexplorer.net]: https://astexplorer.net
[`espree`]: https://github.com/eslint/espree
[`estree`]: https://github.com/estree/estree
Loading
[8]ページ先頭
©2009-2025 Movatter.jp