]>
Commit | Line | Data |
---|---|---|
f2a92ac6 DC |
1 | --- |
2 | title: Contribute to Core Rules | |
3 | eleventyNavigation: | |
4 | key: contribute core rule | |
5 | parent: contribute to eslint | |
6 | title: Contribute to Core Rules | |
7 | order: 10 | |
8 | --- | |
9 | ||
10 | The ESLint core rules are the rules included in the ESLint package. | |
11 | ||
12 | ## Rule Writing Documentation | |
13 | ||
14 | For full reference information on writing rules, refer to [Custom Rules](../extend/custom-rules). Both custom rules and core rules have the same API. The primary difference between core and custom rules are: | |
15 | ||
16 | 1. Core rules are included in the `eslint` package. | |
17 | 1. Core rules must adhere to the conventions documented on this page. | |
18 | ||
19 | ## File Structure | |
20 | ||
21 | Each core rule in ESLint has three files named with its identifier (for example, `no-extra-semi`). | |
22 | ||
23 | * in the `lib/rules` directory: a source file (for example, `no-extra-semi.js`) | |
24 | * in the `tests/lib/rules` directory: a test file (for example, `no-extra-semi.js`) | |
25 | * in the `docs/src/rules` directory: a Markdown documentation file (for example, `no-extra-semi.md`) | |
26 | ||
27 | **Important:** If you submit a core rule to the ESLint repository, you **must** follow the conventions explained below. | |
28 | ||
29 | Here is the basic format of the source file for a rule: | |
30 | ||
31 | ```js | |
32 | /** | |
33 | * @fileoverview Rule to disallow unnecessary semicolons | |
34 | * @author Nicholas C. Zakas | |
35 | */ | |
36 | ||
37 | "use strict"; | |
38 | ||
39 | //------------------------------------------------------------------------------ | |
40 | // Rule Definition | |
41 | //------------------------------------------------------------------------------ | |
42 | ||
43 | /** @type {import('../shared/types').Rule} */ | |
44 | module.exports = { | |
45 | meta: { | |
46 | type: "suggestion", | |
47 | ||
48 | docs: { | |
49 | description: "disallow unnecessary semicolons", | |
50 | recommended: true, | |
51 | url: "https://eslint.org/docs/rules/no-extra-semi" | |
52 | }, | |
53 | fixable: "code", | |
54 | schema: [] // no options | |
55 | }, | |
56 | create: function(context) { | |
57 | return { | |
58 | // callback functions | |
59 | }; | |
60 | } | |
61 | }; | |
62 | ``` | |
63 | ||
64 | ## Rule Unit Tests | |
65 | ||
66 | Each bundled rule for ESLint core must have a set of unit tests submitted with it to be accepted. The test file is named the same as the source file but lives in `tests/lib/`. For example, if the rule source file is `lib/rules/foo.js` then the test file should be `tests/lib/rules/foo.js`. | |
67 | ||
68 | ESLint provides the [`RuleTester`](../integrate/nodejs-api#ruletester) utility to make it easy to write tests for rules. | |
69 | ||
70 | ## Performance Testing | |
71 | ||
72 | To keep the linting process efficient and unobtrusive, it is useful to verify the performance impact of new rules or modifications to existing rules. | |
73 | ||
74 | To learn how to profile the performance of individual rules, refer to [Profile Rule Performance](../extend/custom-rules#profile-rule-performance) in the custom rules documentation. | |
75 | ||
76 | When developing in the ESLint core repository, the `npm run perf` command gives a high-level overview of ESLint running time with all core rules enabled. | |
77 | ||
78 | ```bash | |
79 | $ git checkout main | |
80 | Switched to branch 'main' | |
81 | ||
82 | $ npm run perf | |
83 | CPU Speed is 2200 with multiplier 7500000 | |
84 | Performance Run #1: 1394.689313ms | |
85 | Performance Run #2: 1423.295351ms | |
86 | Performance Run #3: 1385.09515ms | |
87 | Performance Run #4: 1382.406982ms | |
88 | Performance Run #5: 1409.68566ms | |
89 | Performance budget ok: 1394.689313ms (limit: 3409.090909090909ms) | |
90 | ||
91 | $ git checkout my-rule-branch | |
92 | Switched to branch 'my-rule-branch' | |
93 | ||
94 | $ npm run perf | |
95 | CPU Speed is 2200 with multiplier 7500000 | |
96 | Performance Run #1: 1443.736547ms | |
97 | Performance Run #2: 1419.193291ms | |
98 | Performance Run #3: 1436.018228ms | |
99 | Performance Run #4: 1473.605485ms | |
100 | Performance Run #5: 1457.455283ms | |
101 | Performance budget ok: 1443.736547ms (limit: 3409.090909090909ms) | |
102 | ``` | |
103 | ||
104 | ## Rule Naming Conventions | |
105 | ||
106 | The rule naming conventions for ESLint are as follows: | |
107 | ||
108 | * Use dashes between words. | |
109 | * If your rule only disallows something, prefix it with `no-` such as `no-eval` for disallowing `eval()` and `no-debugger` for disallowing `debugger`. | |
110 | * If your rule is enforcing the inclusion of something, use a short name without a special prefix. |