Сторонние форматтеры

В ESLint форматтеры определяют способ представления результатов анализа кода после выполнения линтинга. Сам механизм проверки правил отделён от представления результата, что позволяет гибко менять формат вывода без изменения логики анализа.

Сторонние форматтеры расширяют стандартные возможности вывода и позволяют адаптировать отчёты под конкретные процессы разработки, CI/CD-системы и требования команд.

Архитектура форматирования результатов ESLint

После анализа файлов ESLint формирует массив результатов, где каждый элемент содержит:

  • путь к файлу
  • список сообщений (ошибки и предупреждения)
  • информацию о правиле
  • позицию в коде (строка, колонка)
  • уровень серьёзности

Форматтер получает этот массив и преобразует его в текстовый или структурированный вывод.

Обобщённая схема:

lint results → formatter → output (console / file / CI system)

Разделение анализа и представления делает форматтеры взаимозаменяемыми компонентами.

Стандартные и сторонние форматтеры

ESLint включает несколько встроенных форматтеров:

  • stylish (по умолчанию)
  • compact
  • json
  • checkstyle
  • junit
  • tap
  • html

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

Сторонние форматтеры решают задачи:

  • интеграции с CI/CD
  • генерации отчётов для QA
  • визуализации ошибок в удобочитаемом виде
  • передачи данных в внешние системы аналитики

Подключение стороннего форматтера

ESLint позволяет использовать внешний модуль через параметр --format или -f.

Пример:

eslint . -f eslint-formatter-pretty

При использовании Node.js модуль форматтера загружается динамически через require.

Также возможно указание пути:

eslint . -f ./formatters/custom-formatter.js

Принцип работы стороннего форматтера

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

Базовая сигнатура:

function formatter(results, context) {
    return stringOutput;
}

Где:

  • results — массив объектов результатов анализа
  • context — дополнительная информация (например, cwd, rulesMeta)

Каждый объект результата содержит:

{
  filePath: string,
  messages: Array<{
    ruleId: string,
    message: string,
    line: number,
    column: number,
    severity: 1 | 2
  }>,
  errorCount: number,
  warningCount: number
}

Пример собственного форматтера

module.exports = function(results) {
    let output = '';

    results.forEach(file => {
        if (file.messages.length === 0) return;

        output += `\n${file.filePath}\n`;

        file.messages.forEach(msg => {
            output += `  [${msg.severity === 2 ? 'error' : 'warn'}] `
                    + `${msg.line}:${msg.column} `
                    + `${msg.message} (${msg.ruleId})\n`;
        });
    });

    return output || 'No problems found';
};

Такой форматтер заменяет стандартный вывод и упрощает восприятие ошибок в больших проектах.

Популярные сторонние форматтеры

eslint-formatter-pretty

Используется для человекочитаемого вывода с улучшенной структурой и цветовым выделением. Часто применяется в локальной разработке и CI.

eslint-friendly-formatter

Фокусируется на минималистичном выводе с группировкой ошибок по файлам.

eslint-formatter-json

Преобразует результаты в JSON-структуру для последующей обработки:

eslint . -f json > report.json

Такой формат часто используется в аналитических системах и пайплайнах.

eslint-formatter-html

Генерирует HTML-отчёты, удобные для просмотра в браузере. Применяется в QA-процессах и статических отчётах сборок.

eslint-formatter-junit

Формат JUnit XML используется в системах непрерывной интеграции:

  • Jenkins
  • GitLab CI
  • CircleCI

Пример вызова:

eslint . -f junit > report.xml

Форматтеры и CI/CD процессы

В CI-средах форматтеры выполняют роль адаптера между ESLint и системой отчётности.

Типичные сценарии:

  • генерация отчёта в XML (JUnit)
  • преобразование результатов в JSON для анализа метрик
  • вывод в консоль с минималистичным форматом для логов

Пример pipeline:

eslint src/ -f json -o eslint-report.json

Далее файл может использоваться для:

  • построения графиков качества кода
  • отслеживания технического долга
  • интеграции с системами мониторинга

Интеграция со средствами форматирования кода

В проектах часто используется комбинация Prettier и ESLint.

При этом важно различать роли:

  • ESLint форматтеры отвечают за представление результатов линтинга
  • Prettier отвечает за переформатирование исходного кода

Конфликт возникает, когда оба инструмента пытаются контролировать стиль. Для устранения противоречий применяются:

  • eslint-config-prettier (отключает конфликтующие правила ESLint)
  • eslint-plugin-prettier (интегрирует Prettier в ESLint поток)

Форматтеры ESLint при этом остаются независимым слоем вывода.

Структурные особенности сложных форматтеров

Сложные форматтеры могут включать:

Группировку по файлам

Ошибки агрегируются и сортируются:

  • по пути файла
  • по уровню серьёзности
  • по типу правила

Цветовое оформление

Используются ANSI-escape последовательности для терминалов.

Сводные отчёты

Добавляются итоговые блоки:

  • количество ошибок
  • количество предупреждений
  • процент проблемных файлов

Производительность форматирования

На больших кодовых базах форматтер может стать узким местом.

Факторы влияния:

  • количество файлов
  • объём сообщений
  • сложность форматирования строк
  • синхронная обработка данных

Оптимизации:

  • минимизация строковых конкатенаций
  • использование буферизации вывода
  • отказ от тяжёлых операций внутри циклов

Совместимость форматтеров с версиями ESLint

Форматтеры зависят от структуры объектов результатов. При изменении API ESLint могут происходить:

  • добавление новых полей сообщений
  • изменение структуры контекста
  • расширение метаданных правил

Поэтому сторонние форматтеры часто фиксируют поддерживаемую версию ESLint или используют адаптеры совместимости.

Создание форматтера как часть инфраструктуры проекта

В крупных проектах форматтеры часто:

  • разрабатываются внутри репозитория
  • стандартизируют вывод для всей организации
  • интегрируются с внутренними системами качества кода

Типичная структура:

/tools
  /eslint-formatters
    custom.js
    ci-formatter.js

Использование:

eslint . -f ./tools/eslint-formatters/ci-formatter.js

Форматтеры и анализ качества кода

Сторонние форматтеры становятся частью системы наблюдаемости кода:

  • фиксируют динамику ошибок
  • позволяют строить отчёты между релизами
  • интегрируются с системами метрик

JSON-формат особенно часто используется для автоматического анализа:

{
  "errorCount": 12,
  "warningCount": 5,
  "files": 34
}

Такие данные легко агрегируются и визуализируются.

Расширенные сценарии использования

Форматтеры применяются не только для вывода в консоль:

  • генерация отчётов для веб-панелей
  • интеграция с системами код-ревью
  • преобразование в Slack/Telegram уведомления
  • экспорт в системы статического анализа

В этих случаях форматтер фактически становится трансформером данных ESLint в формат внешней системы.

Оглавление