Настраиваемые форматировщики

Настраиваемые форматировщики позволяют отображать результаты проверки кода в формате, наиболее подходящем для ваших нужд, будь то определённый формат файла, стиль отображения или формат, оптимизированный для конкретного инструмента.

ESLint также имеет встроенные форматировщики, которые вы можете использовать.

Вы можете включить настраиваемые форматировщики в свой проект напрямую или создать пакет npm для их отдельного распространения.

Создание настраиваемого форматировщика

Каждый форматировщик — это функция, которая получает объект results и context в качестве аргументов и возвращает строку. Например, вот как реализован встроенный JSON форматировщик:

//my-awesome-formatter.js
module.exports = function(results, context) {
    return JSON.stringify(results, null, 2);
};

Форматировщик также может быть асинхронной функцией (от ESLint v8.4.0), следующий пример демонстрирует это:

//my-awesome-formatter.js
module.exports = async function(results) {
    const formatted = await asyncTask();
    return formatted;
};

Для запуска ESLint с этим форматировщиком вы можете использовать флаг командной строки -f (или --format). Путь к локально определенному настраиваемому форматировщику должен начинаться с точки (.), например ./my-awesome-formatter.js или ../formatters/my-awesome-formatter.js.

eslint -f ./my-awesome-formatter.js src/

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

Аргумент `results`

Объект results , переданный в форматировщик, представляет собой массив объектов result, содержащих результаты проверки отдельных файлов. Вот пример вывода:

[
    {
        filePath: "/path/to/a/file.js",
        messages: [
            {
                ruleId: "curly",
                severity: 2,
                message: "Expected { after 'if' condition.",
                line: 2,
                column: 1,
                nodeType: "IfStatement"
            },
            {
                ruleId: "no-process-exit",
                severity: 2,
                message: "Don't use process.exit(); throw an error instead.",
                line: 3,
                column: 1,
                nodeType: "CallExpression"
            }
        ],
        errorCount: 2,
        warningCount: 0,
        fixableErrorCount: 0,
        fixableWarningCount: 0,
        source:
            "var err = doStuff();\nif (err) console.log('failed tests: ' + err);\nprocess.exit(1);\n"
    },
    {
        filePath: "/path/to/Gruntfile.js",
        messages: [],
        errorCount: 0,
        warningCount: 0,
        fixableErrorCount: 0,
        fixableWarningCount: 0
    }
]

Объект `result`

Каждый объект в массиве results — это объект result. Каждый объект result содержит путь к проанализированному файлу и информацию о проблемах, обнаруженных при проверке. Вот доступные свойства каждого объекта result:

filePath: Абсолютный путь к проанализированному файлу.
messages: Массив объектов message. Более подробная информация о сообщениях приведена ниже.
errorCount: Количество ошибок в данном файле.
warningCount: Количество предупреждений в данном файле.
stats: Необязательный объект stats, который существует только при использовании параметра stats.
source: Исходный код данного файла. Это свойство опущено, если в этом файле нет ошибок/предупреждений или если присутствует свойство output.
output: Исходный код данного файла с применёнными исправлениями. Это свойство опущено, если исправление недоступно.

Объект `message`

Каждый объект message содержит информацию о правиле ESLint, которое было срабатывало на каком-то фрагменте кода. Доступные свойства каждого объекта message:

ruleId: Идентификатор правила, которое вызвало ошибку или предупреждение. Если ошибка или предупреждение не было вызвано правилом (например, если это ошибка парсинга), это null.
severity: Степень тяжести ошибки, 1 для предупреждений и 2 для ошибок.
message: Человекопонятное описание ошибки.
line: Строка, где расположена проблема.
column: Столбец, где расположена проблема.
nodeType: (Устаревшее: Это свойство будет удалено в будущей версии ESLint.) Тип узла в AST или null , если проблема не связана с конкретным узлом AST.

Аргумент `context`

Функция форматирования получает объект context в качестве второго аргумента. Объект имеет следующие свойства:

cwd: Текущий рабочий каталог. Это значение взято из параметра конструктора cwd класса ESLint.
maxWarningsExceeded (необязательно): Если --max-warnings было установлено и количество предупреждений превысило предел, значение этого свойства — объект, содержащий два свойства:
- maxWarnings: значение параметра --max-warnings
- foundWarnings: количество предупреждений при проверке
rulesMeta: Значения свойств meta правил. Дополнительную информацию о правилах см. на странице Настраиваемые правила.

Например, вот как бы выглядел объект, если бы было запущено правило no-extra-semi:

{
    cwd: "/path/to/cwd",
    maxWarningsExceeded: {
        maxWarnings: 5,
        foundWarnings: 6
    },
    rulesMeta: {
        "no-extra-semi": {
            type: "suggestion",
            docs: {
                description: "disallow unnecessary semicolons",
                recommended: true,
                url: "https://eslint.org/docs/rules/no-extra-semi"
            },
            fixable: "code",
            schema: [],
            messages: {
                unexpected: "Unnecessary semicolon."
            }
        }
    },
}

Примечание: если проверка выполняется устаревшим классом CLIEngine, аргумент context может иметь другое значение, поскольку это зависит от API-пользователей. Пожалуйста, проверьте, является ли аргумент context ожидаемым значением, если вы хотите поддерживать устаревшие среды.

Передача аргументов форматировщикам

Хотя функции форматирования не принимают дополнительные аргументы помимо объекта результатов и контекста, можно передавать дополнительные данные в настраиваемые форматировщики, используя описанные ниже методы.

Использование переменных окружения

Настраиваемые форматировщики имеют доступ к переменным окружения и могут изменять своё поведение на основе данных переменных окружения.

Вот пример, использующий переменную среды FORMATTER_SKIP_WARNINGS для определения того, следует ли отображать предупреждения в результатах:

module.exports = function(results) {
    var skipWarnings = process.env.FORMATTER_SKIP_WARNINGS === "true";

    var results = results || [];
    var summary = results.reduce(
        function(seq, current) {
            current.messages.forEach(function(msg) {
                var logMessage = {
                    filePath: current.filePath,
                    ruleId: msg.ruleId,
                    message: msg.message,
                    line: msg.line,
                    column: msg.column
                };

                if (msg.severity === 1) {
                    logMessage.type = "warning";
                    seq.warnings.push(logMessage);
                }
                if (msg.severity === 2) {
                    logMessage.type = "error";
                    seq.errors.push(logMessage);
                }
            });
            return seq;
        },
        {
            errors: [],
            warnings: []
        }
    );

    if (summary.errors.length > 0 || summary.warnings.length > 0) {
        var warnings = !skipWarnings ? summary.warnings : []; // skip the warnings in that case

        var lines = summary.errors
            .concat(warnings)
            .map(function(msg) {
                return (
                    "\n" +
                    msg.type +
                    " " +
                    msg.ruleId +
                    "\n  " +
                    msg.filePath +
                    ":" +
                    msg.line +
                    ":" +
                    msg.column
                );
            })
            .join("\n");

        return lines + "\n";
    }
};

Вы запустите ESLint с этим настраиваемым форматировщиком и установленной переменной среды следующим образом:

FORMATTER_SKIP_WARNINGS=true eslint -f ./my-awesome-formatter.js src/

Выводом будет:

error space-infix-ops
  src/configs/bundler.js:6:8

error semi
  src/configs/bundler.js:6:10

Сложная передача аргументов

Если шаблон настраиваемого форматировщика не предоставляет достаточно вариантов для желаемого вами форматирования результатов ESLint, лучшим вариантом является использование встроенного JSON форматировщика ESLint и передача вывода в другую программу. Например:

eslint -f json src/ | your-program-that-reads-JSON --option

В этом примере программа your-program-that-reads-json может принять JSON результатов ESLint в сыром виде и обработать его, прежде чем вывести свой собственный формат результатов. Вы можете передать этой программе столько аргументов командной строки, сколько необходимо, для настройки вывода.

Форматирование для терминалов

Современные терминалы, такие как iTerm2 или Guake, ожидают определённый формат результатов для автоматического открытия файлов при нажатии на них. Большинство терминалов поддерживают этот формат для этой цели:

file:line:column

Создание пакета настраиваемого форматировщика

Настраиваемые форматировщики могут распространяться через npm-пакеты. Для этого создайте npm-пакет с именем в формате eslint-formatter-*, где * — имя вашего форматировщика (например, eslint-formatter-awesome). Затем проекты должны установить пакет и использовать настраиваемый форматировщик с флагом -f (или --format), как в этом примере:

eslint -f awesome src/

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

Советы по созданию настраиваемого форматировщика:

Точка входа main должна быть JavaScript-файлом, реализующим настраиваемый форматировщик.
Добавьте эти keywords для помощи пользователям в поиске вашего форматировщика:
- "eslint"
- "eslint-formatter"
- "eslintformatter"

Посмотрите все настраиваемые форматировщики на npm.

Примеры

Форматировщик сводки

Форматировщик, который сообщает только о полном количестве ошибок и предупреждений, будет выглядеть так:

module.exports = function(results, context) {
    // accumulate the errors and warnings
    var summary = results.reduce(
        function(seq, current) {
            seq.errors += current.errorCount;
            seq.warnings += current.warningCount;
            return seq;
        },
        { errors: 0, warnings: 0 }
    );

    if (summary.errors > 0 || summary.warnings > 0) {
        return (
            "Errors: " +
            summary.errors +
            ", Warnings: " +
            summary.warnings +
            "\n"
        );
    }

    return "";
};

Запустите eslint с вышеуказанным форматировщиком сводки:

eslint -f ./my-awesome-formatter.js src/

Это даст следующий вывод:

Errors: 2, Warnings: 4

Подробный форматировщик

Более сложный отчёт может выглядеть так:

module.exports = function(results, context) {
    var results = results || [];

    var summary = results.reduce(
        function(seq, current) {
            current.messages.forEach(function(msg) {
                var logMessage = {
                    filePath: current.filePath,
                    ruleId: msg.ruleId,
                    ruleUrl: context.rulesMeta[msg.ruleId].docs.url,
                    message: msg.message,
                    line: msg.line,
                    column: msg.column
                };

                if (msg.severity === 1) {
                    logMessage.type = "warning";
                    seq.warnings.push(logMessage);
                }
                if (msg.severity === 2) {
                    logMessage.type = "error";
                    seq.errors.push(logMessage);
                }
            });
            return seq;
        },
        {
            errors: [],
            warnings: []
        }
    );

    if (summary.errors.length > 0 || summary.warnings.length > 0) {
        var lines = summary.errors
            .concat(summary.warnings)
            .map(function(msg) {
                return (
                    "\n" +
                    msg.type +
                    " " +
                    msg.ruleId + (msg.ruleUrl ? " (" + msg.ruleUrl + ")" : "") +
                    "\n  " +
                    msg.filePath +
                    ":" +
                    msg.line +
                    ":" +
                    msg.column
                );
            })
            .join("\n");

        return lines + "\n";
    }
};

Когда вы запускаете ESLint с этим настраиваемым форматировщиком:

eslint -f ./my-awesome-formatter.js src/

Вывод будет таким:

error space-infix-ops (https://eslint.org/docs/rules/space-infix-ops)
  src/configs/bundler.js:6:8
error semi (https://eslint.org/docs/rules/semi)
  src/configs/bundler.js:6:10
warning no-unused-vars (https://eslint.org/docs/rules/no-unused-vars)
  src/configs/bundler.js:5:6
warning no-unused-vars (https://eslint.org/docs/rules/no-unused-vars)
  src/configs/bundler.js:6:6
warning no-shadow (https://eslint.org/docs/rules/no-shadow)
  src/configs/bundler.js:65:32
warning no-unused-vars (https://eslint.org/docs/rules/no-unused-vars)
  src/configs/clean.js:3:6

© OpenJS Foundation and other contributors
Licensed under the MIT License.
https://eslint.org/docs/latest/extend/custom-formatters