Внесение вклада в основные правила

Основные правила ESLint — это правила, включённые в пакет ESLint.

Документация по написанию правил

Полную справочную информацию о написании правил см. в разделе Пользовательские правила. Для пользовательских и основных правил используется один и тот же API. Основные различия между основными и пользовательскими правилами:

1. Основные правила включены в пакет eslint.
2. Основные правила должны соответствовать соглашениям, описанным на этой странице.

Структура файлов

Для каждого основного правила ESLint предусмотрены три файла, названных по его идентификатору (например, no-extra-semi).

• в каталоге lib/rules: исходный файл (например, no-extra-semi.js);
• в каталоге tests/lib/rules: файл тестов (например, no-extra-semi.js);
• в каталоге docs/src/rules: файл документации в формате Markdown (например, no-extra-semi.md).

Важно: Если вы отправляете основное правило в репозиторий ESLint, вы должны следовать приведённым ниже соглашениям.

Ниже приведён базовый формат исходного файла правила:

/**
 * @fileoverview Rule to disallow unnecessary semicolons
 * @author Nicholas C. Zakas
 */

"use strict";

//------------------------------------------------------------------------------
// Rule Definition
//------------------------------------------------------------------------------

/** @type {import('../types').Rule.RuleModule} */
module.exports = {
	meta: {
		type: "suggestion",

		docs: {
			description: "disallow unnecessary semicolons",
			recommended: true,
			url: "https://eslint.org/docs/rules/no-extra-semi",
		},
		fixable: "code",
		schema: [], // no options
	},
	create: function (context) {
		return {
			// callback functions
		};
	},
};

Модульные тесты правил

Для принятия каждое встроенное основное правило ESLint должно сопровождаться набором модульных тестов. Файл тестов называется так же, как исходный файл, но находится в каталоге tests/lib/. Например, если исходный файл правила называется lib/rules/foo.js, то файл тестов должен называться tests/lib/rules/foo.js.

ESLint предоставляет утилиту RuleTester, упрощающую написание тестов для правил.

Тестирование производительности

Чтобы процесс линтинга оставался эффективным и ненавязчивым, полезно проверять влияние новых правил или изменений существующих правил на производительность.

О том, как профилировать производительность отдельных правил, см. в разделе Профилирование производительности правил документации по пользовательским правилам.

При разработке в основном репозитории ESLint команда npm run perf позволяет получить общее представление о времени выполнения ESLint со всеми включёнными основными правилами.

$ git checkout main
Switched to branch 'main'

$ npm run perf
CPU Speed is 2200 with multiplier 7500000
Performance Run #1:  1394.689313ms
Performance Run #2:  1423.295351ms
Performance Run #3:  1385.09515ms
Performance Run #4:  1382.406982ms
Performance Run #5:  1409.68566ms
Performance budget ok:  1394.689313ms (limit: 3409.090909090909ms)

$ git checkout my-rule-branch
Switched to branch 'my-rule-branch'

$ npm run perf
CPU Speed is 2200 with multiplier 7500000
Performance Run #1:  1443.736547ms
Performance Run #2:  1419.193291ms
Performance Run #3:  1436.018228ms
Performance Run #4:  1473.605485ms
Performance Run #5:  1457.455283ms
Performance budget ok:  1443.736547ms (limit: 3409.090909090909ms)

Соглашения об именовании правил

В ESLint действуют следующие соглашения об именовании правил:

• Разделяйте слова дефисами.
• Если правило запрещает какое-либо действие, добавьте в начало no-, например no-eval для запрета eval() и no-debugger для запрета debugger.
• Если правило требует наличия чего-либо, используйте короткое имя без специального префикса.

Замороженные правила

Когда работа над функциональностью правил завершена, они помечаются как замороженные (в документации это обозначается символом ❄️). Правила считаются функционально завершёнными, если их предполагаемое назначение реализовано в полном объёме: правило выявляет не менее 80% ожидаемых нарушений и учитывает большинство распространённых исключений. После этого мы ожидаем, что пользователи будут использовать комментарии для отключения правил, если обнаружат неучтённый крайний случай.

Статус замороженного правила означает следующее:

• Исправление ошибок: мы по-прежнему будем исправлять подтверждённые ошибки.
• Новые возможности ECMAScript: мы обеспечим совместимость с новыми возможностями ECMAScript, то есть правило не будет ломаться при использовании нового синтаксиса.
• Поддержка TypeScript: мы обеспечим совместимость с синтаксисом TypeScript, то есть правило не будет ломаться при использовании синтаксиса TypeScript, а выявляемые нарушения будут актуальны для TypeScript.
• Новые параметры: мы не будем добавлять новые параметры, если только параметр не является единственным способом исправить ошибку или обеспечить поддержку новой возможности ECMAScript.

Если вы считаете, что замороженное правило лучше соответствовало бы вашим задачам после внесения изменений, рекомендуем скопировать исходный код правила и изменить его в соответствии с вашими потребностями.