Форматтер html

HTML-форматтер в ESLint предназначен для преобразования результатов анализа кода в структурированный HTML-отчёт, удобный для визуального просмотра в браузере. В отличие от текстовых форматтеров, ориентированных на консоль, HTML-вывод формирует полноценный документ с разметкой, стилями и иерархией ошибок, что делает его особенно полезным для командной разработки, CI/CD-отчётности и аудита качества кода.

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

Ключевые свойства HTML-формата:

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

Подключение и использование

HTML-форматтер используется через CLI ESLint с параметром --format. В стандартной конфигурации он может быть доступен как встроенный или подключаемый модуль.

Пример базового использования:

eslint . --format html

При таком запуске ESLint выполняет анализ текущего проекта и выводит результат в HTML-формате в стандартный поток вывода. Обычно результат перенаправляется в файл:

eslint . --format html > report.html

В расширенных сценариях форматтер может подключаться явно через пакет:

eslint --format ./node_modules/eslint-html-formatter/index.js .

или через npm-пакеты сторонних реализаций HTML-форматирования.

Структура HTML-отчёта

Сформированный HTML-документ имеет иерархическую структуру, которая отражает результаты анализа ESLint.

Типичная структура включает:

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

HTML-структура ориентирована на последовательное восприятие: от общего состояния проекта к конкретным строкам кода.

Секции отчёта

Общая статистика

В верхней части документа отображаются агрегированные данные:

  • общее количество файлов;
  • число ошибок;
  • число предупреждений;
  • итоговый статус проверки.

Эта часть служит индикатором качества кода на уровне всего проекта.

Список файлов

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

  • путь к файлу;
  • количество найденных проблем;
  • статус (чистый / с ошибками / с предупреждениями).

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

Детализация по файлу

Каждое нарушение внутри файла представлено отдельной записью, содержащей:

  • имя правила ESLint;
  • текст сообщения;
  • номер строки и столбца;
  • уровень серьёзности (error / warning).

Пример логической структуры записи:

  • no-unused-vars — переменная объявлена, но не используется
  • строка: 12, столбец: 5
  • уровень: ошибка

Представление правил

HTML-форматтер сохраняет привязку к ESLint-правилам, что позволяет быстро идентифицировать источник проблемы.

Каждое правило отображается как отдельная сущность, обычно с:

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

Некоторые реализации форматтера дополнительно группируют правила по категориям:

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

Группировка ошибок и предупреждений

Одним из ключевых преимуществ HTML-формата является группировка результатов.

Используются следующие уровни агрегации:

По файлам

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

По правилам

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

По уровню серьёзности

Отдельно выделяются:

  • ошибки (blocking issues);
  • предупреждения (non-blocking issues).

Такое разделение помогает приоритизировать исправления.

Стилизация и кастомизация

HTML-форматтер может включать встроенные стили CSS или использовать внешние стили для оформления отчёта.

Распространённые элементы стилизации:

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

Некоторые реализации позволяют модифицировать шаблон HTML:

  • добавлять логотип проекта;
  • изменять структуру отчёта;
  • подключать собственные CSS-файлы;
  • внедрять JavaScript для фильтрации ошибок.

Интеграция в CI

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

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

  1. запуск ESLint в pipeline;
  2. генерация HTML-отчёта;
  3. сохранение отчёта как build artifact;
  4. публикация отчёта в интерфейсе CI.

Пример использования в CI-скрипте:

eslint . --format html > eslint-report.html

Далее файл может быть сохранён в:

  • Jenkins artifacts;
  • GitLab CI reports;
  • GitHub Actions artifacts;
  • локальном сервере отчётов.

HTML-формат удобен тем, что не требует дополнительных инструментов для просмотра — достаточно браузера.

Практики использования

Эффективное применение HTML-форматтера связано с несколькими подходами к организации отчётности.

Архивирование отчётов

Сохранение HTML-файлов по каждому прогону ESLint позволяет отслеживать динамику качества кода.

Сравнение версий

При регулярной генерации отчётов можно анализировать:

  • уменьшение количества ошибок;
  • появление новых нарушений;
  • стабильность code style.

Разделение окружений

HTML-отчёты могут генерироваться отдельно для:

  • production-кода;
  • тестовых окружений;
  • экспериментальных веток.

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

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

Формат представления данных

HTML-форматтер преобразует внутренний JSON-результат ESLint в структурированную DOM-модель.

Базовые элементы представления:

  • контейнер проекта;
  • секции файлов;
  • таблицы ошибок;
  • строки с детализацией;
  • метаданные правил.

Каждый элемент HTML соответствует части диагностического объекта ESLint, что обеспечивает полную трассируемость от отчёта к исходному коду.

Обработка больших проектов

В проектах с тысячами файлов HTML-форматтер сохраняет читаемость за счёт:

  • пагинации (в некоторых реализациях);
  • сворачиваемых блоков;
  • ленивой загрузки секций;
  • оптимизированной структуры DOM.

Это позволяет использовать форматтер даже при анализе монорепозиториев без потери производительности просмотра отчёта.

Оглавление