Пользовательские процессоры

Вы также можете создавать пользовательские процессоры, которые указывают ESLint, как обрабатывать файлы, отличные от стандартных файлов JavaScript. Например, можно написать пользовательский процессор для извлечения и обработки JavaScript из файлов Markdown (пакет @eslint/markdown включает пользовательский процессор для этого).

Спецификация пользовательского процессора

Чтобы создать пользовательский процессор, объект, экспортируемый вашим модулем, должен соответствовать следующему интерфейсу:

const plugin = {
	meta: {
		name: "eslint-plugin-example",
		version: "1.2.3",
	},
	processors: {
		"processor-name": {
			meta: {
				name: "eslint-processor-name",
				version: "1.2.3",
			},
			// takes text of the file and filename
			preprocess(text, filename) {
				// here, you can strip out any non-JS content
				// and split into multiple strings to lint

				return [
					// return an array of code blocks to lint
					{ text: code1, filename: "0.js" },
					{ text: code2, filename: "1.js" },
				];
			},

			// takes a Message[][] and filename
			postprocess(messages, filename) {
				// `messages` argument contains two-dimensional array of Message objects
				// where each top-level array item contains array of lint messages related
				// to the text that was returned in array from preprocess() method

				// you need to return a one-dimensional array of the messages you want to keep
				return [].concat(...messages);
			},

			supportsAutofix: true, // (optional, defaults to false)
		},
	},
};

// for ESM
export default plugin;

// OR for CommonJS
module.exports = plugin;

Метод preprocess принимает содержимое файла и имя файла в качестве аргументов и возвращает массив блоков кода для проверки. Блоки кода проверяются по отдельности, но по-прежнему связываются с именем файла.

У блока кода есть два свойства: text и filename. Свойство text содержит содержимое блока, а свойство filename — его имя. Имя блока может быть любым, но должно включать расширение файла, которое сообщает ESLint, как обрабатывать текущий блок. ESLint проверяет соответствующие записи files в конфигурации проекта, чтобы определить, следует ли проверять блоки кода.

Плагин сам решает, нужно ли возвращать только одну часть файла, не относящегося к JavaScript, или несколько частей. Например, при обработке файлов .html можно объединить все скрипты и вернуть в массиве только один элемент. Однако для файлов .md можно вернуть несколько элементов, поскольку каждый блок JavaScript может быть независимым.

Метод postprocess принимает двумерный массив массивов с сообщениями линтера и имя файла. Каждый элемент входного массива соответствует части, возвращённой методом preprocess. Метод postprocess должен скорректировать расположение всех ошибок так, чтобы оно соответствовало расположению в исходном, необработанном коде, объединить их в единый плоский массив и вернуть его.

Для обнаруженных проблем в каждом сообщении линтера указываются следующие сведения о расположении:

type LintMessage = {
	/// The 1-based line number where the message occurs.
	line?: number;

	/// The 1-based column number where the message occurs.
	column?: number;

	/// The 1-based line number of the end location.
	endLine?: number;

	/// The 1-based column number of the end location.
	endColumn?: number;

	/// If `true`, this is a fatal error.
	fatal?: boolean;

	/// Information for an autofix.
	fix: Fix;

	/// The error message.
	message: string;

	/// The ID of the rule which generated the message, or `null` if not applicable.
	ruleId: string | null;

	/// The severity of the message.
	severity: 0 | 1 | 2;

	/// Information for suggestions.
	suggestions?: Suggestion[];
};

type Fix = {
	range: [number, number];
	text: string;
};

type Suggestion = {
	desc?: string;
	messageId?: string;
	fix: Fix;
};

По умолчанию ESLint не выполняет автоисправления при использовании пользовательского процессора, даже если в командной строке включён флаг --fix. Чтобы разрешить ESLint автоматически исправлять код при использовании вашего процессора, выполните следующие дополнительные действия:

1. Измените метод postprocess, чтобы он также преобразовывал свойство fix обнаруженных проблем. У всех проблем, допускающих автоисправление, есть свойство fix — объект со следующей схемой:

   {
       range: [number, number],
       text: string
   }
   

   Свойство range содержит два индекса в коде, указывающие на начало и конец непрерывного фрагмента текста, который будет заменён. Свойство text содержит текст, которым будет заменён указанный диапазон.

   В исходном списке проблем свойство fix будет указывать на исправление в обработанном JavaScript. Метод postprocess должен преобразовать объект так, чтобы он указывал на исправление в исходном, необработанном файле.

2. Добавьте процессору свойство supportsAutofix: true.

В одном плагине могут быть как правила, так и пользовательские процессоры. В одном плагине также может быть несколько процессоров. Чтобы поддерживать несколько расширений, добавьте каждое из них в элемент processors и укажите для них один и тот же объект.

Как используются объекты meta

Объект meta помогает ESLint кэшировать конфигурации, использующие процессор, и выводить более понятные отладочные сообщения.

Объект meta плагина

Объект meta плагина содержит сведения о самом плагине. Если процессор указан в строковом формате plugin-name/processor-name, ESLint автоматически использует meta плагина для создания имени процессора. Это наиболее распространённый способ указания процессоров.

Пример:

// eslint.config.js
import { defineConfig } from "eslint/config";
import example from "eslint-plugin-example";

export default defineConfig([
	{
		files: ["**/*.txt"], // apply processor to text files
		plugins: {
			example,
		},
		processor: "example/processor-name",
	},
	// ... other configs
]);

В этом примере имя процессора — "example/processor-name", и именно это значение будет использоваться при сериализации конфигураций.

Объект meta процессора

Каждый процессор также может указать собственный объект meta. Эти сведения используются, когда объект процессора передаётся непосредственно в processor в конфигурации. В этом случае ESLint не знает, какому плагину принадлежит процессор. Свойство meta.name должно соответствовать имени процессора, а свойство meta.version — версии npm-пакета ваших процессоров. Проще всего получить эти сведения, прочитав их из вашего package.json.

Пример:

// eslint.config.js
import { defineConfig } from "eslint/config";
import example from "eslint-plugin-example";

export default defineConfig([
	{
		files: ["**/*.txt"],
		processor: example.processors["processor-name"],
	},
	// ... other configs
]);

В этом примере при непосредственном указании example.processors["processor-name"] используется собственный объект meta процессора. Он должен быть определён, чтобы процессор корректно обрабатывался, когда на него ссылаются не через имя плагина.

Зачем нужны оба объекта метаданных

Рекомендуется, чтобы и плагин, и каждый процессор предоставляли соответствующие объекты метаданных. Это гарантирует, что функции, использующие объекты метаданных, такие как --print-config и --cache, будут работать корректно независимо от того, как процессор указан в конфигурации.

Указание процессора в файлах конфигурации

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

// eslint.config.js
import { defineConfig } from "eslint/config";
import example from "eslint-plugin-example";

export default defineConfig([
	{
		files: ["**/*.txt"],
		plugins: {
			example,
		},
		processor: "example/processor-name",
	},
]);

Подробнее см. раздел «Указание процессора» в документации по настройке плагинов.