Встроенные форматтеры

Форматтеры в ESLint отвечают за преобразование результатов анализа кода в человекочитаемый или машинно-обрабатываемый вид. Линтер после проверки файлов формирует массив сообщений о нарушениях правил, но сам по себе не определяет, как именно эти данные будут отображаться. Эту задачу выполняет форматтер.

Каждое сообщение ESLint содержит структурированную информацию: файл, строку и столбец, идентификатор правила, уровень серьёзности, текст ошибки, а также дополнительные поля (например, диапазон исправления fix при наличии автофиксации). Форматтер получает этот набор данных и преобразует его в конкретный формат вывода: текстовый отчёт, JSON, XML, таблицу или специализированную структуру для CI-систем.

Использование форматтеров в CLI

Выбор форматтера осуществляется через параметр CLI --format (или сокращённо -f):

eslint . --format stylish

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

Дополнительно результат можно сохранять в файл:

eslint . -f json > report.json

или использовать для интеграции в CI:

eslint . -f checkstyle > checkstyle-report.xml

Форматтер применяется уже после завершения анализа и не влияет на сам процесс линтинга.

Структура сообщения, передаваемого форматтеру

Каждое сообщение о проблеме имеет стандартную форму:

  • ruleId — идентификатор правила
  • severity — уровень (1 предупреждение, 2 ошибка)
  • message — текст ошибки
  • line, column — позиция
  • endLine, endColumn — конец диапазона (если применимо)
  • fix — объект автоправки (если доступен)
  • filePath — путь к файлу

Форматтер работает с массивом таких сообщений, сгруппированных по файлам.

Встроенные текстовые форматтеры

stylish

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

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

Особенность заключается в визуальной структуре: файл, затем список нарушений с выравниванием и указанием позиции.

compact

Минималистичный формат вывода, предназначенный для быстрого просмотра:

file.js: line 10, col 5, Error - Unexpected console statement.

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

unix

Формат, совместимый с Unix-утилитами. Каждая ошибка выводится в виде строки:

file.js:10:5: Unexpected console statement

Подходит для интеграции с grep, awk и другими инструментами обработки текста.

table

Выводит результаты в табличной форме. Каждая строка соответствует нарушению, а колонки фиксируют файл, позицию, правило и сообщение.

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

Форматтеры для CI и машинной обработки

json

Возвращает полный структурированный JSON-объект. Используется для:

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

Пример структуры:

[
  {
    "filePath": "file.js",
    "messages": [
      {
        "ruleId": "no-console",
        "severity": 2,
        "message": "Unexpected console statement",
        "line": 10,
        "column": 5
      }
    ],
    "errorCount": 1,
    "warningCount": 0
  }
]

json-with-metadata

Расширенная версия JSON-формата. Помимо результатов содержит:

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

Применяется в сложных CI/CD пайплайнах и системах аналитики.

checkstyle

XML-формат, совместимый с инструментами непрерывной интеграции (например, Jenkins). Структура соответствует стандарту Checkstyle:

<checkstyle>
  <file name="file.js">
    <error line="10" column="5" severity="error" message="Unexpected console statement"/>
  </file>
</checkstyle>

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

junit

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

Применяется в CI для отображения результатов линтинга в интерфейсах тест-раннеров.

tap

Формат Test Anything Protocol. Каждое нарушение представляется как тестовый кейс:

not ok 1 - Unexpected console statement in file.js:10:5

Используется в Node.js экосистеме и тестовых пайплайнах.

Форматтеры для визуальных интерфейсов

html

Генерирует HTML-отчёт с навигацией по файлам и подсветкой ошибок. Обычно используется для публикации результатов анализа в виде статического отчёта.

Особенности:

  • группировка по файлам
  • кликабельные ссылки
  • цветовая дифференциация severity

visualstudio

Формат, совместимый с интеграцией Visual Studio. Вывод адаптирован под отображение в списке ошибок IDE.

Используется в средах, где ESLint интегрируется как внешний анализатор кода.

codeframe

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

Пример поведения:

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

Особенности обработки форматтеров

Пайплайн формирования вывода

Процесс выглядит следующим образом:

  1. ESLint анализирует файлы
  2. Формирует массив результатов
  3. Передаёт их выбранному форматтеру
  4. Форматтер преобразует данные в строку или структуру
  5. Результат выводится в stdout или файл

Форматтер не участвует в логике анализа и не может изменять результаты.

Отсутствие форматтера

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

Создание пользовательских форматтеров

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

export default function (results) {
  return results.map(r => r.filePath).join('\n');
}

Функция получает массив results, где каждый элемент содержит:

  • filePath
  • messages
  • errorCount
  • warningCount
  • fixableErrorCount
  • fixableWarningCount

Результатом должна быть строка (или структура, если используется JSON-форматирование).

Использование кастомного форматтера

eslint . -f ./my-formatter.js

или через пакет:

eslint . -f eslint-formatter-custom

Принципы разработки форматтеров

Форматтеры строятся вокруг нескольких ключевых принципов:

  • отсутствие побочных эффектов
  • чистая функция преобразования данных
  • независимость от конфигурации ESLint
  • детерминированный вывод

При необходимости сложной логики (например, агрегации статистики) она реализуется внутри форматтера, но не влияет на исходные данные линтера.

Работа с большими проектами

При анализе крупных кодовых баз форматтеры становятся частью инфраструктуры качества:

  • JSON используется для агрегации метрик
  • HTML — для визуального аудита
  • compact и unix — для потоковых логов
  • stylish — для локальной разработки

Разделение форматов позволяет использовать один и тот же результат анализа в разных контекстах без изменения конфигурации ESLint.

Оглавление