Вывод результатов в файл

ESLint предоставляет несколько механизмов сохранения результатов анализа кода в файл, начиная от стандартного перенаправления stdout и заканчивая встроенными параметрами CLI и программным API. Основой вывода служит система форматтеров, которая определяет структуру итогового отчёта.

Базовый принцип формирования вывода

Результат работы ESLint формируется в два этапа:

  1. Анализ файлов и построение массива найденных проблем (lint results).
  2. Применение форматтера, преобразующего структуру данных в текстовый или структурированный формат.

Форматтер определяет вид вывода:

  • текстовый (например, stylish)
  • структурированный (json, checkstyle, junit)
  • пользовательский

После форматирования результат может быть направлен в stdout или записан в файл.

Перенаправление вывода через оболочку

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

eslint . > eslint-report.txt

В этом случае используется форматтер по умолчанию, а весь вывод CLI сохраняется в файл.

Для сохранения ошибок отдельно от стандартного потока применяется перенаправление stderr:

eslint . 2> eslint-errors.txt

Однако такой способ ограничен:

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

Параметр --output-file (-o)

Встроенный механизм ESLint для записи результата в файл основан на параметре --output-file:

eslint . -o report.txt

или сокращённая форма:

eslint . -o report.txt

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

  • записывает именно отформатированный результат линтинга
  • используется вместе с параметром --format
  • не требует перенаправления stdout

Пример с выбором форматтера:

eslint . -f stylish -o report.txt

Выбор форматтера через --format

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

eslint . -f json -o report.json

Наиболее часто используемые форматтеры:

stylish

Человекочитаемый формат по умолчанию.

eslint . -f stylish -o report.txt

json

Структурированный формат для последующей обработки.

eslint . -f json -o report.json

JSON-формат включает:

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

junit

Используется в CI/CD системах.

eslint . -f junit -o junit-report.xml

checkstyle

Подходит для интеграции с Java-инструментами.

eslint . -f checkstyle -o checkstyle.xml

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

Формат json является наиболее универсальным для программной обработки:

[
  {
    "filePath": "src/index.js",
    "messages": [
      {
        "ruleId": "no-unused-vars",
        "severity": 2,
        "message": "'x' is assigned a value but never used",
        "line": 1,
        "column": 5
      }
    ],
    "errorCount": 1,
    "warningCount": 0
  }
]

Такой формат позволяет:

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

Запись нескольких файлов в один отчёт

ESLint агрегирует результаты анализа всех переданных файлов:

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

Результат:

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

Пользовательские форматтеры

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

eslint . -f ./formatters/custom-formatter.js -o report.txt

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

module.exports = function(results) {
  return results
    .map(file => `${file.filePath}: ${file.errorCount}`)
    .join('\n');
};

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

  • принимает массив результатов анализа
  • возвращает строку
  • позволяет формировать любые структуры (CSV, Markdown, HTML)

Программный API и запись в файл

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

import { ESLint } from "eslint";
import fs from "fs";

const eslint = new ESLint();

const results = await eslint.lintFiles(["src/**/*.js"]);

const formatter = await eslint.loadFormatter("json");
const output = await formatter.format(results);

fs.writeFileSync("report.json", output);

Ключевые этапы:

  • запуск анализа через lintFiles
  • получение форматтера через loadFormatter
  • генерация строки отчёта
  • запись через файловую систему

Асинхронная запись больших отчётов

При больших проектах используется потоковая запись:

import fs from "fs";
import { ESLint } from "eslint";

const eslint = new ESLint();
const results = await eslint.lintFiles(["src"]);

const formatter = await eslint.loadFormatter("json");

const stream = fs.createWriteStream("report.json");
stream.write(await formatter.format(results));
stream.end();

Такой подход снижает нагрузку на память при больших объёмах данных.

Интеграция с CI/CD

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

eslint . -f json -o eslint-report.json

Далее файл:

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

Exit code и его влияние на запись

ESLint завершает работу с кодом выхода:

  • 0 — ошибок нет
  • 1 — найдены ошибки

Запись в файл происходит независимо от exit code:

eslint . -f json -o report.json

Даже при ошибках файл формируется полностью.

Комбинирование stdout и файла

Вывод можно дублировать:

eslint . -f stylish | tee report.txt

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

eslint . -f json -o report.json

Различие:

  • tee работает на уровне shell
  • --output-file работает внутри ESLint

Ограничения вывода в файл

Существуют технические особенности:

  • служебные сообщения (warnings CLI) могут не попадать в файл
  • при отсутствии прав записи файл не создаётся
  • некоторые форматтеры ориентированы только на stdout
  • JSON-формат требует корректного парсинга массива результатов

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

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

eslint . -f json -o report.json
eslint . -f stylish

Либо через кастомный форматтер, который пишет в несколько потоков.

Форматирование как ключевой элемент вывода

Система форматтеров является центральным элементом механизма записи:

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

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

Оглавление