|
| 1 | +# Custom ESLint rules |
| 2 | + |
| 3 | +We use a set of custom [ESLint](http://eslint.org) to enforce repo specific coding rules and styles. These custom rules are run in addition to many standard ESLint rules we enable in the project. Some example custom rules includes: |
| 4 | + |
| 5 | +- Enforcing proper code layering |
| 6 | +- Preventing checking in of `test.only(...)` |
| 7 | +- Enforcing conventions in `vscode.d.ts` |
| 8 | + |
| 9 | +Custom rules are mostly used for enforcing or banning certain coding patterns. We tend to leave stylistic choices up to area owners unless there's a good reason to enforce something project wide. |
| 10 | + |
| 11 | +This doc provides a brief overview of how these rules are setup and how you can add a new one. |
| 12 | + |
| 13 | +# Resources |
| 14 | +- [ESLint rules](https://eslint.org/docs/latest/extend/custom-rules) — General documentation about writing eslint rules |
| 15 | +- [TypeScript ASTs and eslint](https://typescript-eslint.io/blog/asts-and-typescript-eslint/) — Look at how ESLint works with TS programs |
| 16 | +- [ESTree selectors](https://eslint.org/docs/latest/extend/selectors) — Info about the selector syntax rules use to target specific nodes in an AST. Works similarly to css selectors. |
| 17 | +- [TypeScript ESLint playground](https://typescript-eslint.io/play/#showAST=es) — Useful tool for figuring out the structure of TS programs and debugging custom rule selectors |
| 18 | + |
| 19 | + |
| 20 | +# Custom Rule Configuration |
| 21 | + |
| 22 | +Custom rules are defined in the `.eslint-plugin-local` folder. Each rule is defined in its own TypeScript file. These follow the naming convention: |
| 23 | + |
| 24 | +- `code-RULE-NAME.ts` — General rules that apply to the entire repo. |
| 25 | +- `vscode-dts-RULE-NAME.ts` — Rules that apply just to `vscode.d.ts`. |
| 26 | + |
| 27 | +These rules are then enabled in the `eslint.config.js` file. This is the main eslint configuration for our repo. It defines a set of file scopes which rules should apply to files in those scopes. |
| 28 | + |
| 29 | +For example, here's a configuration that enables the no `test.only` rule in all `*.test.ts` files in the VS Code repo: |
| 30 | + |
| 31 | +```ts |
| 32 | +{ |
| 33 | + // Define which files these rules apply to |
| 34 | + files: [ |
| 35 | + '**/*.test.ts' |
| 36 | + ], |
| 37 | + languageOptions: { parser: tseslint.parser, }, |
| 38 | + plugins: { |
| 39 | + 'local': pluginLocal, |
| 40 | + }, |
| 41 | + rules: { |
| 42 | + // Enable the rule from .eslint-plugin-local/code-no-test-only.ts |
| 43 | + 'local/code-no-test-only': 'error', |
| 44 | + } |
| 45 | +} |
| 46 | +``` |
| 47 | + |
| 48 | +# Creating a new custom rule |
| 49 | +This walks through the steps to create a new eslint rule: |
| 50 | + |
| 51 | +1. Create a new rule file under `.eslint-plugin-local`. Generally you should call it `code-YOUR-RULE-NAME.ts`, for example, `.eslint-plugin-local/code-no-not-null-assertions-on-undefined-values.ts` |
| 52 | + |
| 53 | +2. In this file, add the rule. Here's a template: |
| 54 | + |
| 55 | + ```ts |
| 56 | + /*--------------------------------------------------------------------------------------------- |
| 57 | + * Copyright (c) Microsoft Corporation. All rights reserved. |
| 58 | + * Licensed under the MIT License. See License.txt in the project root for license information. |
| 59 | + *--------------------------------------------------------------------------------------------*/ |
| 60 | + |
| 61 | + import * as eslint from 'eslint'; |
| 62 | + |
| 63 | + export = new class YourRuleName implements eslint.Rule.RuleModule { |
| 64 | + |
| 65 | + readonly meta: eslint.Rule.RuleMetaData = { |
| 66 | + messages: { |
| 67 | + customMessageName: 'message text shown in errors/warnings', |
| 68 | + }, |
| 69 | + schema: false, |
| 70 | + }; |
| 71 | + |
| 72 | + create(context: eslint.Rule.RuleContext): eslint.Rule.RuleListener { |
| 73 | + return { |
| 74 | + [SELECTOR]: (node: any) => { |
| 75 | + // Report errors if needed |
| 76 | + return context.report({ |
| 77 | + node, |
| 78 | + messageId: 'customMessageName' |
| 79 | + }); |
| 80 | + } |
| 81 | + }; |
| 82 | + } |
| 83 | + }; |
| 84 | + ``` |
| 85 | + |
| 86 | + - Update the name of the class to match the name of your rule |
| 87 | + - Add message entries for any errors you want to report |
| 88 | + - Update `SELECTOR` with the [ESTree selector](https://eslint.org/docs/latest/extend/selectors) needed to target the nodes you are interested in. Use the [TypeScript ESLint playground](https://typescript-eslint.io/play/#showAST=es) to figure out which nodes you need and debug selectors |
| 89 | + |
| 90 | +3. Register the rule in `eslint.config.js` |
| 91 | + |
| 92 | + Generally this is just turning on the rule in the rule list like so: |
| 93 | + |
| 94 | + ```js |
| 95 | + rules: { |
| 96 | + // Name should match file name |
| 97 | + 'local/code-no-not-null-assertions-on-undefined-values': 'warn', |
| 98 | + ... |
| 99 | + } |
| 100 | + ``` |
| 101 | + |
| 102 | +Rules can also take custom arguments. For example, here's how we can pass arguments to a custom rule in the `eslint.config.js`: |
| 103 | + |
| 104 | +``` |
| 105 | +rules: { |
| 106 | + 'local/code-no-not-null-assertions-on-undefined-values': ['warn', { testsOk: true }], |
| 107 | + ... |
| 108 | +} |
| 109 | +``` |
| 110 | +
|
| 111 | +In these cases make sure to update the `meta.schema` property on your rule with the JSON schema for the arguments. You can access these arguments using `context.options` in the rule `create` function |
| 112 | +
|
| 113 | +
|
| 114 | +## Adding fixes to custom rules |
| 115 | +Fixes are a useful way to mechanically fix basic linting issues, such as auto inserting semicolons. These fixes typically work at the AST level, so they are a more reliable way to perform bulk fixes compared to find/replaces. |
| 116 | +
|
| 117 | +To add a fix for a custom rule: |
| 118 | +
|
| 119 | +1. On the `meta` for your rule, add `fixable: 'code'` |
| 120 | +
|
| 121 | +2. When reporting an error in the rule, also include a `fix`. This is a function that takes a `fixer` argument and returns one or more fixes. |
| 122 | +
|
| 123 | +See the [Double quoted to single quoted string covert fix](https://github.com/microsoft/vscode/blob/b074375e1884ae01033967bf0bbceeaa4795354a/.eslint-plugin-local/code-no-unexternalized-strings.ts#L128) for an example. The ESLint docs also have [details on adding fixes and the fixer api](https://eslint.org/docs/latest/extend/custom-rules#applying-fixes) |
| 124 | +
|
| 125 | +The fixes can be run using `npx eslint --fix` in the VS Code repo |
0 commit comments