Форматтер json и json-with-metadata

Форматтеры в ESLint определяют способ представления результатов статического анализа кода. Они преобразуют внутреннюю структуру отчёта линтера в конкретный формат вывода, пригодный для чтения человеком или для обработки внешними системами. Среди машинно-ориентированных форматтеров особое значение имеют json и json-with-metadata, поскольку они формируют структурированные данные, пригодные для CI/CD, аналитики и автоматизированной обработки.

Роль JSON-форматтеров в архитектуре ESLint

ESLint после анализа файлов формирует единый объект отчёта, содержащий:

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

Форматтеры json и json-with-metadata сериализуют этот отчёт в JSON-структуру, сохраняя его пригодность для программного потребления без потери семантики.

JSON formatter

Форматтер json формирует массив объектов, где каждый объект соответствует одному проанализированному файлу.

Общая структура вывода

[
  {
    "filePath": "src/index.js",
    "messages": [],
    "errorCount": 0,
    "warningCount": 0,
    "fixableErrorCount": 0,
    "fixableWarningCount": 0,
    "source": "console.log('test')\n"
  }
]

Основные поля объекта файла

filePath Путь к анализируемому файлу. Используется для сопоставления результатов с исходной кодовой базой.

messages Массив найденных нарушений правил ESLint.

errorCount / warningCount Количество ошибок и предупреждений соответственно.

fixableErrorCount / fixableWarningCount Число проблем, которые могут быть автоматически исправлены через --fix.

source Исходный код файла (опционально, зависит от конфигурации ESLint).

Структура messages

Каждое сообщение о проблеме представляет собой объект со следующими полями:

{
  "ruleId": "no-console",
  "severity": 2,
  "message": "Unexpected console statement.",
  "line": 1,
  "column": 1,
  "endLine": 1,
  "endColumn": 13,
  "nodeType": "MemberExpression"
}

Описание полей сообщения

ruleId Идентификатор правила, вызвавшего нарушение. Может быть null, если ошибка не связана с конкретным правилом.

severity Уровень критичности:

  • 1 — предупреждение (warning)
  • 2 — ошибка (error)

message Текст диагностического сообщения.

line / column Начальная позиция проблемы в коде.

endLine / endColumn Конечная позиция диапазона, если применимо.

nodeType Тип AST-узла, к которому относится нарушение.

Использование JSON formatter в CLI

В CLI ESLint форматтер задаётся параметром -f или --format:

eslint -f json src/

Вывод можно перенаправить в файл:

eslint -f json src/ > report.json

Это делает форматтер удобным для интеграции с системами:

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

json-with-metadata formatter

Форматтер json-with-metadata расширяет базовый JSON-вывод, добавляя глобальные метаданные выполнения ESLint.

Общая структура

{
  "metadata": {
    "rulesMeta": {},
    "eslintVersion": "8.57.0"
  },
  "results": [
    {
      "filePath": "src/index.js",
      "messages": [],
      "errorCount": 0,
      "warningCount": 0,
      "source": "console.log('test')\n"
    }
  ]
}

Метаданные в json-with-metadata

eslintVersion

Содержит версию ESLint, которая использовалась при анализе. Это критично для:

  • воспроизводимости результатов;
  • диагностики различий между версиями;
  • аудита CI-процессов.

rulesMeta

Объект, содержащий метаданные правил, участвовавших в анализе.

Каждое правило может включать:

  • описание;
  • категорию;
  • ссылку на документацию;
  • схему опций.

Пример:

{
  "no-console": {
    "docs": {
      "description": "disallow the use of console",
      "category": "Possible Errors",
      "recommended": true
    },
    "schema": []
  }
}

Структура results

Поле results в json-with-metadata аналогично массиву из json, но находится внутри общего объекта. Каждый элемент содержит ту же структуру, что и в стандартном JSON-форматтере:

  • filePath
  • messages
  • errorCount
  • warningCount
  • fixableErrorCount
  • fixableWarningCount
  • source (если включён)

Отличия json и json-with-metadata

Структурные различия

  • json — массив результатов;
  • json-with-metadata — объект с двумя ключами: metadata и results.

Наличие глобальной информации

json не содержит сведений о:

  • версии ESLint;
  • правилах и их метаданных.

json-with-metadata включает эти данные, делая отчёт самодостаточным.

Практическое применение различий

json

Используется в сценариях, где важна компактность:

  • быстрый парсинг в скриптах;
  • интеграция с простыми CI-пайплайнами;
  • отправка результатов в сторонние сервисы мониторинга.

json-with-metadata

Применяется там, где требуется контекст выполнения:

  • построение аналитических систем качества кода;
  • хранение исторических отчётов;
  • сравнение результатов между версиями ESLint;
  • диагностика поведения правил.

Обработка результатов в автоматизированных системах

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

Типичный сценарий обработки включает:

  • парсинг JSON;
  • группировку ошибок по ruleId;
  • агрегацию по файлам;
  • вычисление плотности ошибок;
  • построение метрик качества.

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

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

Особенности сериализации

При генерации JSON ESLint придерживается строгой структуры:

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

Ограничения формата

Несмотря на универсальность JSON-формата, существуют особенности:

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

Интеграционные сценарии

JSON-форматтеры ESLint часто используются в связке с:

  • системами CI/CD (GitHub Actions, GitLab CI);
  • инструментами качества кода (SonarQube-подобные решения);
  • внутренними API аналитики;
  • логирующими системами;
  • инструментами автоматической проверки pull request’ов.

Структурированность данных позволяет строить поверх ESLint полноценные системы наблюдения за качеством кодовой базы.

Оглавление