Настраиваемые процессоры

Вы также можете создать настраиваемые процессоры, которые расскажут 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 example from "eslint-plugin-example";

export default [
    {
        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 example from "eslint-plugin-example";

export default [
    {
        processor: example.processors["processor-name"]
    },
    // ... other configs
];

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

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

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

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

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

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

export default [
    {
        plugins: {
            example
        },
        processor: "example/processor-name"
    }
];

См. Указание процессора в документации по конфигурации плагинов для получения дополнительной информации.